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Introduction 


The intent of this book is to supplement the class readings and lecture notes for CSCI 360: 
Computer Programming in Assembler Language. It should be used in conjunction with the 
text Assembler Language with ASSIST and ASSIST/I; it is by no means intended to replace 
the text. See the ESA/390 Principles of Operation manual for further help on the machine 
instructions, and the High Level Assembler Language Reference for more information on the 
assembly language. 








Chapter 1 - Syllabus 


Course Description 
CSCI 360, Computer Programming in Assembler Language is "an in-depth study of assembler 
language programming on a third-generation computer, including internal and external 
subroutines, conditional assembly, and the macro language. Students are required to write a 


number of substantial programs. Extensive laboratory work. PRQ: CSCI 220, CSCI 230. 
CSCI 240, or CSCI 250." - from the Undergraduate Catalog of Northern Illinois University. 


Required Course Texts 


L Assembler Language with ASSIST and ASSIST/I (Fourth Edition, 1990), by Overbeek 
and Singletary 


Z. GX20-1850: System/370 Reference Summary (yellow booklet) 


ai CSCI 360 Notes and Examples for the current semester 


Recommended Course Texts 


l. SA22-7201: ESA/390 Principles of Operation (available online) 
Z. SC26-4940: High Level Assembler Language Reference (available online) 
> SC26-4941: High Level Assembler Programmer's Guide (available online) 


4. ASSIST Introductory Assembler User's Manual (available online) 





Policies and Procedures 


General 


Students are expected to read and observe the rules of this syllabus as well as the Other 
Academic Policies specified in the appropriate Undergraduate or Graduate Catalog of Northern 
Illinois University. 


Assignments 


There will be about eleven programming assignments plus a few homework assignments. 
The point value of each assignment will be announced when the assignment is distributed. 


Write the following information under the front of each program you turn in: 


Your name 

Instructor's name 

Course and section numbers 

Assignment number (Program 1, Homework 2, etc) 
Date and time due 


To assure receipt of full credit, a program must meet two deadlines. It must be run by the due 
date and time specified by the instructor, and it must be turned in by the date and time 
specified by the mstructor. The initiation date and time printed in the job log will be used to 
determine a program's run time. A program which fails to meet either deadline will have a 
reduction in score and may possibly earn zero points. There are no "free extensions." 


You must do all of the programming and homework assignments given out in this course. In 
most programming courses, and in this course in particular, the operation of later 
programming assignments builds on the work of earlier ones. It is therefore a particularly 
significant requirement in this course that all programming assignments reach a level of 
essential completion so that the foundation exists upon which succeeding assignments may be 
built. 


Any program that does not show, in the instructor's opinion, a reasonable attempt at 
completing the assignment will not be accepted. Such unacceptable programs must be brought 
to an acceptable status (to be determined by the instructor) and turned in to the instructor 
within one week of the original due date. Failure to comply with this rule may result in the 
reduction of the final grade for the course by one letter for each such assignment. 


Backup Copies 
You are responsible for keeping a backup hard copy (paper) of each assignment you hand in, 


with a run time stamp no later than that required for the assignment. Also, be prepared to 
submit an electronic version of your programs to your instructor at any time. 
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Grading of Assignments 


The teaching assistant for your section will grade all assignments. If you do not agree with this 
evaluation, you must confer with the assistant first. If you still are not satisfied, bring the 
program to your instructor. The instructor will examine it and assign a final grade (which 
could be higher, lower or the same as the original grade). Any protest of assignment scores 
must be made within one week of the date the assignment is returned to you. Any protests 
made after this time will not be considered. 


Programming assignments will be graded on output, coding technique, and documentation. All 
programs must follow the rules of structured programming. Programs with unstructured code 
will lose points on coding technique. Programs which fail to comply with the requirements 
(written or verbal) of the assignment are subject to the loss of all pomts. The grading 
scheme for programs 1s approximately as follows: 


Output and compliance 


with requirements SOS 

Coding technique 22% 

Documentation 259% 
Exams 


There will be two 150-point mass exams plus a 200-point comprehensive final exam. The final 
exam will be given during the period scheduled for it. In addition, there may be several 
quizzes (possibly unannounced). If you must miss an exam due to illness, you must notify your 
instructor before exam time. You must verify the illness with a note from your doctor. Any 
protest of test scores must be made within one week of the date the test is returned to 
you. Any protests made after this time will not be considered. 


Final Grade 


Your final course average will be computed as: 
Final Average = (Assignment Average * .3) + (Test Average * .7) 
Assignment Average = (earned assignment points/maximum assignment points) * 100 
Test Average = (earned Test Points)/(maximum possible Test Points) * 100 
Test Points = exam points + quiz points/4 


Letter grades will be assigned on the following scale of averages: 


92% -100% 
Under 92% = B 
Under 84% = C 
D 
F 


I 
> 


Under /6% = 


Under 68% = [but see the next statement] 
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Important: You must have a passing average (68% or above) on each of the Assignment 
Average and Test Average in order to pass the course. In addition, the final grade for the 
course will not exceed by more than one letter the lower of the Assignment Grade and the Test 
Grade. 


Attendance 


Students are expected to attend all meetings of the class, arriving prior to the start of class and 
remaining for the full duration of the class. Assignments that are due at a given class meeting 
(programs, homework, questions, etc.) must be deposited on the table prior to the start of class 
in order to be "turned in on time." 


Unexcused absence will result in a score of zero on any quiz or exam given in that period. 
Notification of the instructor (not just the department office) about an impending or 
just-occurred absence is vastly superior to after-the-fact (e.g., not until the next class!?) 
notification. Most matters can be dealt with if prompt (preferably prior) notification occurs. 


You are responsible for everything said and handed out in class, including any modification of 
assignments or course requirements. If you should miss a class, be sure to get notes from one 
or more of your classmates. See your instructor for any handouts you may have missed. There 
will be no private repeat performances of lectures from your instructor. Reasonable questions, 
of course, will be answered. Bring the Reference Summary (yellow booklet) to every class. 
You will likely find it helpful to bring all required texts to each class meeting. 


Debugging Assistance 


Instructors and teaching assistants are more than willing to help students who, in turn, are 
willing to help themselves (by working hard). When you come for help, you must bring an 
executed (and fully documented) copy of your program (with a dump) and you are expected 

to have made an honest attempt to debug the abending program. You should know the logic of 
your program, the abending instruction, contents of related fields, contents of related registers, 
and a possible cause of the abend. 


Always remember to bring back the previous run of your program (which we may have 
marked up with appropriate corrections that you need to have performed) to facilitate our 
understanding of your problem. You need to bring with you all appropriate references to 
which we might make reference during the debugging session. You will know that you still 
need work in the area of defining "all" if your answer to one of our questions during a 
debugging session 1s; "...No, I don't know the answer to that question, and I guess it could be 
found in my class notes, which I don't have with me!" 


We want you to learn to solve your own problems. Give it your best shot. Then, if you still 
need help, come see us. 
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Cheating 


DON'T DO IT! Cheating in any form will not be tolerated. Your instructor and/or the Judicial 
Office will determine the punishment. Your instructor is required by the University to report 
all cheating to the Judicial Office. Although you may discuss course topics with other class 
members, remember that your assignment must reflect your own work. The following are 
clear examples of cheating: 


I. Two or more people working so closely together on an assignment that the programs 
handed in are identical in logic. 


Z. Two or more people working on a program where each does a part and the combined 
result 1s one program. 


i Any person letting anyone else use a flowchart, program listing, or any form of 
program code to write and/or debug his/her program. Both the lender and the borrower 


are guilty of cheating. 


4. Any person picking up or using a file, flowchart, program listing or any form of 
program code which is not the result of her/his own work 


1] 








——— 


—— 








Chapter 2 - Job Control Language (JCL) 


Once we have an assembler program coded, all we need to do is add JCL and we can run it. 
Our finished program appears below. See the JCL section for help on JCL. See the 
Documentation Standards section for more help on documentation standards. Use the Assist 
JCL unless otherwise told. 


Assist JCL 


//jobname JOB ,'banner name' ,MSGLEVEL=(1,0) 
/* JOBPARM NOLOG, ROOM=your-bin-num 
// EXEC ASSIST 
//SYSIN DD * 
Your assembler program source code goes here 
(If your input data is instream data, then insert it after the END statement in your program. ) 


/* 


// 
SUBSTITUTIONS: 
jobname = Znnnnnnx, where Znnnnnn is your assigned logonid and x is a 
single letter or number. 
banner name = will print on your job banner. 1-20 characters. 
your-bin-num = your issued bin number. 


AN EXAMPLE: 
//Z123456A JOB ,'JOE A. STUDENT' ,MSGLEVEL= (1,0) 
/* JOBPARM NOLOG , ROOM=1234 
// EXEC ASSIST 
//SYSIN DD * 
TITLE 'A SIMPLE PROGRAM ! 


KKK KKK KKK KEKE KEKE KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKEKEKEKEEKSE 


* * 
x Documentation goes here ...... * 
* * 
KEK KKK KKK KEKE KR KEKE KEKE KKK KKK KKK KKK KKK KK KK KKK KKK KKK KKK KKK KKEKSE 
MAIN Comer 


USING MAIN,15 


END MAIN 
345 
645 
768 35 546 32 
/* 
// 
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ee 


er 


If your program requires input data from a disk file, then the JCL after the assembler source 
code should change as follows: 


//Z2987654B JOB ,'JOE A. STUDENT' ,MSGLEVEL= (1,0) 
/*JOBPARM NOLOG, ROOM=1234 


J / EXEC ASSIST 
//FTO5F001 DD DSN=name-of-file,DISP=SHR 
//SYSIN DD * 


TITLE 'A SIMPLE PROGRAM ' 


kK KK KK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KEKE KEKE KEKE KE 


x * 
x Documentation goes here ...... i 
* * 
KK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK K KKK KEKKKKEKEKEKEKEKEKKEKEKEKE KEKE KEKE 
MAIN Conc.) 


USING MAIN, 15 


END MAIN 
/* 
// 


SUBSTITUTIONS: 


name-of-file = When a program requires data from an input disk file. 
The instructor will give you the name of the file. 


NOTE: When coding JCL, you must code everything exactly as shown, except for the 
substitution items; otherwise, you will receive JCL errors. 


Also note that on the line of JCL that defines the file to be used, FTOSFOO1 contains zeroes 
and not any letters O. 
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Assembler JCL 


Use assembler JCL only when specifically told by your instructor. The first assembler JCL is 
used for programs requiring input data files. 


//Z2918273C JOB ,'JOE A. STUDENT' ,MSGLEVEL= (1,0) 
/*JOBPARM NOLOG,ROOM=1234 


/ /PROC JCLLIB ORDER= (T9OCSCI .CSCI464 . PROCLIB) 
//STEP1 EXEC HLA464CG 
//SYSIN DD “ 


TITLE ‘A SIMPLE PROGRAM ' 


KKK KEK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK IKEEKEKH 


* * 
* Documentation goes here ...... * 
* * 


KKK KKK KKK KKK KK KKK KKKE KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KK KKEKHKHE 


MAIN CoG. 
USING MAIN, 15 


E}ND MAIN 
/* 
//GO.XREAD DD DSN=name-of-file,DISP=SHR 
//GO.SYSOUT DD SYSOUT=A 
// 
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a | 


This second example of assembler JCL is used when the programmer wishes to uses her own 
test data on the program first. 


//Z192837D JOB ,'JOAN A. STUDENT' ,MSGLEVEL= (1,0) 
/* JOBPARM NOLOG, ROOM=1234 


/ [PROC JCLLIB ORDER= (T9OCSCI .CSCI464.PROCLIB) 
//STEP1 EXEC HLA464CG 
//SYSIN DD al 


TITLE "A SIMPLE PROGRAM ! 


KEKKKKKKKRKEKKRKKKEKKKKKKKK KKK KK KKK KKK KK KKK KKK KKK KKK KKEKEKEKEKEEKSE 


* * 
* Documentation goes here ...... x 
* 3 
KKKKKKKEKKKKK KKK KKK KKK KK KKK KKK KK KKK KKK KK KKK KKK KKK KE KKKEKSE 
MAIN Cong. 


USING MAIN,15 


END MAIN 
/* 
//GO.XREAD DD * 


your input stream of data is entered here! 


//GO.SYSOUT DD SYSOUT=A 
// 
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JCL for Listing the Input Data Set 


All assignments will be available via web browser, and will have a link to a web copy of any 
input data set. In case there is no such link, you can use the following JCL to submit a batch 
job to obtain the input data listing. The following example will print the listing of the input 
data for an assignment. For each subsequent assignment, just modify the SYSUTI statement 
to reflect the name of the input data set given to you on the assignment sheet. 


//Z657483E JOB ,'JOE A.STUDENT' 
//PRINT EXEC PGM=IEBPTPCH 
//SYSPRINT DD SYSOUT=A 
J foto. DD DSN=name-of-file, DISP=SHR 
SI SYoUL. DD SYSOUT=A 
//SYSIN DD * 
PRINT MAXFLDS=1 
RECORD FIELD=(80,1,,1) 
/* 
/ / 


SUBSTITUTIONS: 


name-of-file = When a program requires data from an input file. The 
instructor will give you the name of the file. 


Another Way to View the Input Data Set 


Much simpler than the above, use your FTP client to access the file. The name of the site 1s 
MVS.CSO.NIU.EDU and you should specify the T90 ID of the instructor as the remote site 
folder. Each client has its own setup rules, so no further information can be provided here, 
except to say that the data files for CSCI 360 can usually be seen by double-clicking on the file 
name once the FTP connection has been established. 


There is an important rule, however: be SURE to specify an ASCII transmission, not a 
BINARY one (which is often the default). If you get garbage, try again with ASCII. 


16 

















Chapter 3 - Documentation Standards 


Routine (Main Box) Documentation 


Each routine, whether internal or external, should contain a star box that looks like the following: 


SLO IRR el Fae Ce tg ae aR RCRD NORCO AI SR RA ie Dee hee sa eS ee iron Scene Seika Gee Jae 


* 
* NAME: 
* 
* 
* FUNCTION: 
1 
* 
* 
x INPUT: 
* 
* 
* OUTPUT: 
* 
* 
* ENTRY CONDS: 
* 
* 


*REGISTER USAGE: 


BALL CONDS: 


NiO dy Se 


* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 


* 
* 
* 
* 
* 
* 
*  PSEUDOCODE: 
* 
* 
* 
* 
* 
* 
* 


WAAKKKEKEKKEKKKKKKEKEKKKKKKKKEKKKEKKKKKKKKKKEKKKKKKKKKK KEK KKK 


NAME: This should be the name of the routine, usually the first label in the 
routine, that the caller references (e. g., a CSECT label for external 
routines). 


FUNCTION: This should be a one or more line description of what the routine is 
supposed to do. 
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INPUT: This is a description of the physical data that is read by this routine. A 
routine only has input if it contains an XREAD command. The content 


of a table is NOT input, it is storage. If there are no inputs, you must 
say 'NONE'. 


OUTPUT: This is a description of any information sent to the printer, such as 
reports. A routine only has output if it contains an XDUMP or XPRNT 
command. If there are no outputs, you must say'NONE'’. 


ENTRY CONDS: This stands for Entry Conditions. This should describe the parameters 
passed to the subroutine. If there no parameters passed, then you must 


type in 'NONE'. Examples of valid entry conditions follow later 1n this 
section. 


EXIT CONDS: This stands for Exit Conditions. This should represent what registers the 
routine will purposely change before returning back to the calling routine 
(for external routines only register 15 and O can be used) . If there are 
no register exit conditions, you must type in 'NONE'. Examples of valid 
entry conditions follow later on in this section. 


Examples of Entry and Exit Conditions for internal subroutines: 


ENTRY CONDS: R3 -- Contains the address of beginning of table 
Pa =<— Contains. the address of the card 
FXIT CONDS: R5 -- Contains the address of the end of table 


The above may be abbreviated for space as follows. 


ENTRY CONDS R3 -- @(BEGINNING OF TABLE) 
R4 -- @ (CARD) 
EXIT CONDS: R5 -- @(END OF TABLE) 


Examples using a parameter list: 


ENTRY CONDS: R1 -- @(PARMLIST) 
O(R1) -- @(BEGINNING OF TABLE) 
4(R1) -- @(CARD) 
8(R1) -- @FULLWORD[@(LOGICAL END OF TABLE) ] 


EXIT CONDS: R15 -- CONTAINS RETURN CODE 
O -- MEANS SUCCESSFUL 
4 -- MEANS UNSUCCESSFUL 
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REGISTER USAGE: Register usage should describe what registers are being used 
consistently in the following section of code. An example 


follows: 
R6 -- USED FOR THE STABLE DSECT USING 
R7 -- CONTAINS THE ADDRESS OF THE END OF THE TABLE 
R15 -- USED AS A BASE REGISTER 


PSEUDOCODE: _ This should show all the pseudocode that you used to write this routine. 
In addition, each major step in the pseudocode should have a step 
number off to the left, and a matching documentation statement in the 
assembler source code. This is to provide a sort of index into the source 
code from the pseudocode. Pseudocode should be independent of the 
assembler language. Don't use assembler words (register) or 
instructions ( XDECI, XDECO, etc. ) The algorithm should be just as 
easy to implement in COBOL, FORTRAN, BASIC or any other 
programming language. See, also the section titled A Complete Program 
for an example of pseudocode. 


****  T)on't follow the examples in the book for writing the pseudocode. 


**** Would anyone reading the following pseudocode be able to tell that an 
assembler programmer wrote it? 


kK KKK KKK KKK KK KKK KKK KK KKK KKK KKK KKK KK KKK KEKEKEKEKEKKK KKK KEKE KKK 


i PSBEUDOCODE 

* <1> INITIALIZE THE ACCUMULATORS 

* <2> GET THE. Pikol nECORD 

* <3> DO WHILE (NOT EOF’) 

" DUMP THE CARD 

* <4> IF (NUMBER POSITIVE) 

. ADD NUMBER TO POSITIVE ACCUMULATOR 
as ELSE : 

x ADD NUMBER TO NEGATIVE ACCUMULATOR 
= ENDIF 

* <92 GET NEXT CARD 

is E.NDDO 

* <6> PRINT THE TOTAL 

kok KK KK KK I KK KKK KK KK KK KKK KKK KK KKK KR KKK KKK KKK KKK KK KK KKK KKK 


Another example: 
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. PSEUDOCODE Il 


<STEP 1> INITIALIZE THE ACCUMULATORS 
<STEP 2> READ THE Fino! RECORD 
<STEP 3> DO WHILE (NOT END OF FILE) 


+ + + 

















* 
* < 
* 
* 
* 
* 
* < 
* 
* < 
KAKKRKKKK 


NOTES: 


NOTE: 


Example 


CARD 
PLINE 
SUM 
NAME 





DUMP THE RECORD READ 
OTEP 4> ITF (NUMBER POSITIVE) 
ADD NUMBER TO POSITIVE ACCUMULATOR 
BLSE 
ADD NUMBER TO NEGATIVE ACCUMULATOR 
ENDIF 
Slee DS READ NEXT RECORD 
E;NDDO 
STEP 6> PRINT THE TOTAL 


REE ARRARRAERKR KEE RRRR ERD ERK REAKRARERERER BHR Ee 


This should specify any special programming techniques that this routine uses 
that someone looking at your program should know about. If there are no 
special notes, you may omit this line. In addition to the above documentation 
box, your program should implement the follow ing standards: 


Source Code Documentation 
You MUST follow all documentation standards beginning with the very first 


programming assignment! 


Line Documentation 


You must provide Line Documentation on 80% or more of executable 
instructions or execution of your program will be suppressed. 


Documentation should usually start in column 36 and should be kept aligned. 


LA 37 LAB LE Load R3 with @ of table - Bad! 
LA 3, TABLE Get table beginning @ - Good 

AR 3,4 Add R4 to R3 - Bad doc! 

AR 3,4 Add amount to total - Good 
XDECI 6,CARD Put converted number in —- Good 
ST 6, TABLE the table 

MV I Pea Clear the = Good 
MVC PLINE+1 (132) , PLINE print line 


Documenting storage: 


BES CL80O Input area 

DC Cl2'THE SUM IS:!' (Don't have to document). 

DS CZ Storage area for the total. 
DS Ci2Z0 Storage area for name. 
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Spacing Source Code 
TITLE ‘write a suitable title for that page' 
--- Type TITLE in columns 10-14. 
--- This will advance the source code to a new page and print a specified title. 


--- This will also print the specified title on all the following pages until next 
TITLE statement is encountered. 


oe Use at least one TITLE per program. Should have one for each CSECT, 
subroutine, macro, DSECT etc. 


Note: To print an apostrophe or ampersand, code two of them in the header. Don't 
use a TITTLE and an EJECT one right after the other or you will end up with a 
blank page. 


ex. TITLE ‘STORAGE FOR THE MAIN ROUTINE' 
re fo Oak 


ex. TITLE "MODULE - MAIN' Appears on all pages until another TITLE statement 
appears 


SPACE n - To leave specified number of blank lines in source listing. 


- Use space to break large pieces of source code into small, readable sections. If n 
is omitted then, default is 1. 


SPACE , Gives one blank line 
SPACE 3 Gives three blank lines 


Code SPACE 1n source code like this: 


AR 3,4 Add R4 to R3 

AR i ee! Add amount to total 
SPACE 2 

XDECI 6, CARD Put number in 

eb 6, TABLE the table 
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Your printout will look like this: 


AR 3,4 Add R4 to R3 
AR 3; 4 Add amount to total 
XDECI 6, CARD Put number in 
5 6, TABLE the table 
EJECT --- EJECTs are used for advancing the source code to a new page (for 


example, starting a routine on a new page). 


--- EJECTS are also used to indicate major breaks in logic and to increase 
readability of the program. 


Example (Skips to the top of the next page): 
joint 14 


EJUEC'L 
LTORG 


Puts the LTORG at the top of the next page 


REMEMBER! Don't use a TITLE and an EJECT one right after the other or you will 
end up with a blank page!!! 


oH 











Macro Documentation Standards 


The following minimal documentation should be placed in all macro definitions. 


ie 


Describe the function of the macro; what it does for the user. Do NOT describe how 
the macro works. To the user, the macro is Just an instruction and the user only wants 
to know how to use itt. 


Describe the symbolic parameter s including coding specifications. 


Documentation example: 


* 


* 
* 
* 
* 
* 
* 
* 
* 
_x* 
Pa 
* 
* 
* 
* 
* 
* 
* 
* 
* 


* 
* 
* 
* 
* 
. 
_* 
* 
* 
* 
* 
* 
* 
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* 

NAME : CHANGE x 
* 

FUNCTION: TO CONVERT THE VALUE IN &REG INTO ITs x 
DECIMAL EQUIVALENT AND TO EDIT THE VALUE * 

INTO THE 12 BYTE OUTPUT AREA DESIGNATED By + 

THE &PRNTFLD ADDRESS. * 

* 

PROTOTYPE STATEMENT: 
& LABEL ZDECO &REG, &PRNTFL * 

* 

SYMBOLIC PARAMETERS: 
& LABEL AN OPTIONAL LABEL FOR THE FIRST STATEMENT . 
GENERATED . 

& REG REQUIRED OPERAND IN THE FORM OF A REGISTER * 
NUMBER CONTAINING THE BINARY VALUE TO BE * 

CONVERTED TO A PRINTABLE FORMAT. 

&PRNTFLD A REQUIRED OPERAND IN THE FORM OF ANY VALID * 
RX-TYPE ADDRESS INTO WHICH THE DECIMAL, . 

EQUIVALENT OF THE BINARY VALUE IS TO BE . 

EDITED. . 

* 

ERROR CONDITIONS: x 
IF EITHER &REG OR &PRNTFLD IS MISSING, AN MNOTE AND . 
MEXIT ARE ISSUED. . 

* 

NOTES: x 
THE CONTENTS OF CALLERS REGISTERS 1 AND 2, AND THE 
CONDITION CODE, ARE SAVED AND RESTORED UPON EXIT FROM « 

THE MACRO. x 

* 

BO Dae RPE Aste Bee Tee Pe ST et Pe De er 2D pe Sc De Rie ae he eee ho gle Fee dee oe Dede ee See deg Ai dene eh he at, eens 
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NAME: This should be the name of the macro. 


FUNCTION: This should be a one or more line description of what the macro is 
supposed to be used for. 


PROTOTYPE: This should show what parameters this macro accepts and the order the 
parameters should be specified to call the macro. 


SYMBOLIC PARMS: This is a description of all symbolic parameters, what they mean, 
any defaults they may have, and if they are optional. If there are 
no parameters, then 'NONE' must be specified. 


ERROR CONDS: This should be a listing of any MNOTE messages that may be generated 
by this macro, as well as under what conditions they will be generated. 
If there are no error conditions, you must say'NONE'. 


NOTE >: This should specify any special programming techniques that this macro 
uses that someone looking at your program should know about. 


Internal Macro Documentation: 
There are two kinds of documentation which should appear within a macro definition: 
documentation which will appear as generated assembler source, and documentation 
which describes the operation of the macro instruction itself, particularly conditional 


assembly. 


The first, assembler source documentation, should be written exactly as is done in a 
standard assembler language program. 


The second, macro language documentation, should appear as both comment blocks 
(using the .* form of macro comment) and as line doc on conditional assembly 


Statements. 


Remember, there is never “too much” documentation. 
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Chapter 4 - Structured Pseudocode 


Structured programming provides the programmer logical constructs from which to build 
efficient programs. It facilitates simplified logic, easier debugging, and better maintenance. 
Structured programming is best demonstrated through the use of pseudocode. Pseudocode is 
an English like language that allows the description of logic to be written, free from the syntax 
of a formal computer language. Therefore, a particular set of pseudocode becomes portable. 
That is, it may be shared with different programmers, each of which may work with a 
different language, and it will be readily understood. Actual computer programming simply 
becomes the translation of pseudocode into a computer language. The following are four basic 
control constructs that we will use in pseudocode to give our programs good structure: 


sequence (straight-line) 
if-else 

if-elseif-else 

do-while 


~ © & 


In addition, these four constructs may be layered within themselves. For example, a 
do-while construct may contain an if-else construct, which definitely will contain a sequence 
construct. To better demonstrate the use of structured pseudocode, both computer code 
examples and examples relating to something from everyday life will be given. Remember, 
pseudocode is a description of logic, therefore it can define any process. 


Sequence Construct 


The sequence construct is simply a list of one or more instructions that should be executed 
consecutively. There is no decision to be made, just instructions to be performed unconditionally. 
Such as 


X=5.2 
Y=X* 3 
PRINI A, XY 


PULL UP TO GAS STATION 
REMOVE NOZZLE ON GAS PUMP 
INSERT NOZZLE IN GAS TANK 
FILL TANK WITH GAS 

REPLACK NOZZLE ON GAS PUMP 
PAY FOR GAS 

LEAVE GAS STATION 


A sequence of instructions is always embedded in the three other constructs. 
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If-Else Construct 


The if-else structure tests a condition, then executes a construct of instructions based if the 
result of the condition was true. Optionally, a different sequence construct of instructions may 
be executed in the event the result of the condition was false. That is, if the condition 1s true, then 

one group of logic is processed, otherwise, a different group of logic may be processed. 


To set up an if-else construct, follow the these steps: 
l. Place an ‘IF’ command, followed by the condition to be tested on the top line. 


2. Indent, and place the sequence of instructions that should be executed if the result of the 
condition 1s true. 


3. If there is a separate sequence of instructions to be executed 1f the resultis false, place an 
'ELSE' command in the same column as the 'IF", then on the next line and indented, 
place the sequence of instructions. 


4. Place an 'ENDIF' command in the same column as the 'IF' command to signal the end 
of the if-else structure. 


Examples of valid if-else structures follow: 


READ X 
IF X = 0 
Y=0 
PRINT 'Division by zero avoided.' 
ELSE 
Y=100/X 
ENDIF 


ITF CAR LOW ON GAS 
PULL INTO GAS STATION 
REMOVE NOZZLE ON GAS PUMP 
INSERT NOZZLE IN GAS TANK 
FILL TANK WITH GAS 
REPLACE NOZZLE ON GAS PUMP 
PAY FOR GAS 
LEAVE GAS STATION 
ELSE 
DRIVE PAST GAS STATION 
ENDIF 


IF WINDSHIELD IS DIRTY 
CLEAN WINDSHIELD 
ENDIF 
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If-Elself-Else Construct 


The if-elseif-else construct also test a condition, then executes a sequence of instructions based on 
whether the result of the condition was true. Unlike the IF-ELSE construct which allows only 
one condition to be tested, the if-elseif-else construct allows for a list of conditions to be tested, 
executing the sequence of instructions provided when a condition tests true. Optionally, a 
different sequence of instructions may be executed in the event that none of the tested conditions 
weretrue. That is, if the first condition is true, then one group of logic is processed, otherwise, 
the second condition is tested. If it is true, then its logic is processed, other wise another condition 
may be tested. This may repeat for as long as you would like. In addition, an alternative group 
of logic may be specified in the event that ALL the previous conditions where not met. 


To set up an if-elseif-else structure, follow these steps: 
L. Place an 'IF’ command, followed by the condition to be tested on the top line. 


2. Indent, and place the sequence of instructions that should be executed if the result of the 
condition 1s true. 


3. Place an 'ELSEIF' command in the same column as the 'IF", followed by the next 
condition to be tested. Then on the next line and indented, place the sequence of 
instructions to be executed if this condition resulted in true. Repeat this step for as many 
choices you have to be made. 


4. If there is a separate sequence of instructions to be executed if ALL the previous 
conditions resulted is false, place an 'ELSE' command in the same column as the 'IF’, 
then on the next line and indented, place the sequence of instructions. 


2. Place an'ENDIF' command in the same column as the 'IF" command to signal the end 
of the if-elseif-else structure. 


Examples of valid if-elseif-else structures follow: 
READ TRANSACTION-CODE 


IF TRANSACTION-CODE = '‘'A' 
ADD THE NEW STUDENT RECORD 
PRINT THE NEW STUDENT RECORD 

ELSEIF TRANSACTION-CODE = !'D'! 
DELETE THE CURRENT STUDENT 
PRINT A DELETE MESSAGE 

ELSEIF TRANSACTION-CODE = 'E' 
EDIT THE CURRENT STUDENT 
PRINT THE CHANGES 

ELSE 


2/ 


PRINT ‘INVALID TRANSACTION CODE' 
ENDIF 


IF HOME STEREO DOES NOT WORK 
ITF NO POWER 
CHECK TO MAKE SURE UNIT IS PLUGGED IN 
CHECK TO MAKE SURE POWER OUTLET WORKS 
BLSEIF NO SOUND 
CHECK SPEAKERS 
BLSE 
CALL MANUFACTURER 
ENDIF 
ENDL 


Do-While Construct 


It is often necessary to repeat a sequence of instructions. The Do-While structure will repeat a 
sequence of instructions for as long as some defined condition is true. When the condition is no 
longer true, execution continues at the next instruction after the do-while. That is, a group of 
logic is repeated for as long as some condition remains true. 


The following guidelines for designing a do-while loop should be used: 
L Place a'DO' command, followed by the condition to be tested on the top line. 


2. Indent, and place the sequence of instructions that should be executed if the result of the 
condition 1s true. 


a3 Place an'ENDDO' command in the same column as the 'DO' command to signal the end 
of the Do-While structure. 


Examples of a valid do-while constructs follow: 


READ RECORD 
DO WHILE... (NOL BEND=-OF-P LGE) 
PROCEOo RECORD 
READ NEXT RECORD 
ENDDO 


DO WHILE DIRTY DISHES ON COUNTER 
GRAB DISH 
WASH DISH 
RINSE. Diol 
DRY Dion 
PUT DISH AWAY IN CUPBOARD 
ENDDO 
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Converting Pseudocode to Assembler Code 


Once pseudocode has been written, the writing of an assembler program merely becomes an act 
of translation. Let's first look at some pseudocode we would like to convert into assembler. This 
portion of pseudocode describes how to read an unknown number of cards, each card with an 
unknown number of values. It should print out each number, along with a message that says 
whether it was positive, negative, or zero. If no numbers where pulled, it should print an error 
message. 


ROUTINE: CHECKNUM 
COUNT = 0 
READ FIRST CARD 
DO WHILE (NOT END-OF-FILE) 
ATTEMPT TO GET NUMBER FROM CARD 
DO WHILE (SUCCESSFUL) 
COUNT = COUNT + lL 
PUT NUMBER ON PRINTLINE 
TF NUMBER = 0 
10 PUT 'ZERO' ON PRINTLINE 


Oo OAINOPWNE 


dep 8 ELSEIF NUMBER < 0 

LZ PUT 'NEGATIVE' ON PRINTLINE 
LS ELSE 

14 PUT *POSITIVE” ON PRINTING 
i ENDIF 

ii PRINT PRINTLINE 

17 ATTEMPT TO GET NEXT NUMBER FROM CARD 
18 ENDDO 

de, READ NEXT CARD 

20 E.NDDO 

Za: IF COUNT = 0 

oe PRINT 'NO NUMBERS FOUND' 

a2 ENDIF 

24 RETURN 


Note that the line numbers to the left are there only for reference purposes. The first thing that 
we should do is to label each do-while, if-else, and if-elseif-else construct. The label names we 
chose should conform to the assembler language standards of being up to eight characters in 
length, and starting with a letter from the alphabet. See the ASSIST text book for more 
‘nformation about assembler label names. A good practice is to chose labels that indicate the 
structure of the logic, not the logic's function. The logic will contain documentation to indicate 
its function. A simple method is to take the first character of the routines name and concatenate 
it with the pseudocode keyword command (such as DO, IF, ELSEIF, ELSE, ENDIF, ENDDO. ) 
Keep a mental counter for each type of do-while, if-else, and if-elseif-else construct within the 
current routine. You can use this to distinguish each embedded structure from the next, as the 

assembler will require each label to be unique. | 
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CDO1 


CDECZ 


Cie ot 


CELSEILA 


CE LSE 


CENDIF1L 


CENDDO2 


CENDDO1 — 


CIF2 


CENDIF2 


Statement Type 


ROUTINE 


no label 


DO 


IF 


The best illustration of this is an example. 


ROUTINE: CHECKNUM 
COUNT = 0 
READ FIRST CARD 
DO WHILE (NOT END-OF-FILE) 
ATTEMPT TO GET NUMBER FROM CARD 
DO WHILE (SUCCESSFUL) 
COUNT = COUNT + 1 
PUT NUMBER ON PRINTLINE 
TF NUMBER = O 
PUT 'ZERO' ON PRINTLINE 
ELSEIF NUMBER < 0 
PUT 'NEGATIVE'T ON PRINTLINE 
ELSE 
PUT 'POSITIVE' ON PRINTLINE 
ENDIF 
PRINT PRINTLINE 
ATTEMPT TO GET NEXT NUMBER FROM CARD 
ENDDO 
READ NEXT CARD 
ENDDO 
IF COUNT = O 
PRINT 'NO NUMBERS FOUND' 
ENDIF 
RETURN 


Our sample pseudocode now contains assembler labels for each pseudocode command. Now we 
need to define the process of converting pseudocode into assembler code. 


Action 


Code the routine name as the CSECT. 
Establish addressability 


Encode the one pseudocode instruction into as many assembler 
instructions as it takes to complete. 


Place the label in the left-hand column; 
Set the condition code if necessary. 
Branch to the matching ENDDO if the condition is not met. 


Place the label in the left-hand column. 

Set the condition code if necessary. 

Branch to the next label belonging within the IF structure (ie 
ELSEIF, ELSE, or ENDIF) if the condition 1s not met. 
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Statement Type 


ELSEIF 


ELSE 


ENDIF 


ENDDO 


RETURN 





Action 


Branch unconditionally to the ENDIF. 

Place the label in the left-hand column. 

Set the condition code if necessary. 

Branch to the next label belonging within the current IF structure 
(ie ELSEIF, ELSE, or ENDIF) when the condition is not met. 


Branch unconditionally to the ENDIF. 
Place the label in the left-hand column and leave a place holder 
(such as DS OB). 


Place the label in the left-hand column and leave a place holder 
(such as DS OB). 


Branch unconditionally to the corresponding DO label this ENDDO 
closes. Place the label in the left-hand column and leave a place 
holder (DS OH). 


Code the assembler instructions to return to the caller. Code an 
LTORG, then any storage this routine will need. 


3] 








uy 
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WN 


14 
15 
16 
ae 
18 


19 
20 


21 
Ze 


£5 
24 


CHECKNUM 


2131645 


CDO2 


Sei i ya 


CELSEILA 


CELSEL 


CENDIF1 


CENDDO2 


CENDDO1 
CiEZ 


CENDIF2 


CARD 


PLINE 
OUTNUM 


OUTMSG 


Our program now looks like the following: 


et Oe § 
USING CHECKNUM, 15 
OR Sy 
XREAD CARD, 80 
BNZ CENDDO1 
XDECI 2, CARD 
BO CENDDO2 
LA 3,1(,3) 
XDECO 2,OUTNUM 
BNZ CELSEILA 
MVC OUTMSG, =CL20' ZERO’ 
B CENDIF 1 
BNM CELSEL 
MVC OUTMSG, =CL20'NEGATIVE' 
B CENDIF1 
DS OH 
MVC OUTMSG, =CL20'POSITIVE' 
DS OH 
XPRNT PLINE, 56 
ADEGI. Zaye ty 2 


B CDO2 
DS OH 
XREAD CARD, 80 
B CDoOL 
DS OH 
LR of 


BNZ CENDIF2 
XPRNT =CL20' NO NUMBERS FOUND", 20 
DS OH 


BR 14 

LTORG 

DC chev" 

DG Ce 

DC CL16' NUMBER READ WAS' 
DC on 

DC CL8' AND IS ' 

De Chzo* * 


END CHECKNUM 
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10. 


Chapter 5 - Debugging Tips 


Chapter 2 of Text 


Spelling mistakes. 
a. NUM for NUMB. 


Omit USING statement. Will cause a lot of addressability errors. 
a. Failure to assign and load enough base registers for a long program. 


b. Using the base register for another purpose in the program thereby destroying the 
base reference. 


Violating rules for declarative. 


a. DS with a nominal value, which is viewed as documentation. 

b DC without a nominal value. 

c Wrong length on a DC --- DC CL3'DATE'’. 

d Wrong nominal value coded --- DC CL5'0" gives 'Obbbb' rather than '00000'. 


Select the correct instruction. 


LR 7,4 LOAD CONTENTS OF R4 INTO R7/. 
L 71,4 LOAD CONTENTS OF BYTES 4, 5, 6, 7 INTO R7. 
LA 7,4 LOADS THE 4 INTO R/7/. 


Errors may not occur if you use the wrong instruction, but your output will be incorrect. 


Binary division requires that the even register be initialized with the sign bit of the odd 
register. 


Binary calculations may generate unexpectedly large values that exceed the capacity of one 
register. 


Use XDUMPs to verify register contents and storage. 
When using EQU be sure you code in what you want. 
R12 EQU a 
Whenever you say R12 the compiler will interpret it as a 13. 
Remember the rules of using literals and the LTORG statement. 


When using apostrophes, ampersands, or quotes you are required to use two of them next 
to each other in a literal in order to represent just one of them. 
C2 ee iS" ---> E350C47DE2 
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Chapter 3 of Text 


l. Incorrect use of the mnemonic branching, reversing operand | and 2, using BNH rather 
than BNL. 

2. The increment value for stepping through the table may be wrong. 

3. The beginning or end of table address may be wrong. 

4. If beginning or end of table addresses are wrong, you may never find the end of table and 





get into an infinite loop. You will probably end up with a protection exception as you go 
through memory. 


5. Work in steps. Build table, dump and verify. Sort table, Dump and verify. Print table, 
dump and verify. 


Chapter 4 of Text 
NOTE: If an instruction is not completely understood and may be causing an error, check 
the assembler manual to insure for it's correct use. 
1. Coding a length on MVI or CLI or on the second operand of MVC or CLC. 


2. Be sure that input definition agrees with actual input record. Any differences may cause 
garbage results. 


> Omitting explicit length on an MVC statement with relative addressing: 
MVC PRINT+95 ,=C'DATE' 
The computer will move 133 bytes starting from the first byte of DATE. 


4. Using Literal ("=") with a CLI or MVI. 


Chapter 5 of Text 


Assembly errors: 


Le Coding packed DCs (type P) with values other than digits 0-9. 
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Coding hex data - pads and truncates on the left. 
DC XL3'FFE" generates ‘OOOOFF' rather than’ FFFFFF' 


Logic errors: 


1. 


10. 


Be 


12. 


Packing a field that contains a blank will give an invalid sign (X’' 04' ) and an attempt to do 
arithmetic with this field will cause a data exception. Most likely cause is an invalid input 
record. 


Another cause of a data exception is using a field not initialized by DC or defined as 
Character or Hex. 


Watch out for using MVC and CLC on packed data (incorrect execution) and ZAP or CP 
on character data (Data exception). 


Watch for improper relative addressing. 

Missing explicit lengths can cause unexpected results. 
Double check MVC/ED operations. 

a. There must be an odd number of digit selectors. 
b. Print area field must be the same as the edit field. 
Watch for too short a field in MP. Data exception. 
Make sure field is big enough on DP. Decimal divide. 


Make sure you don't divide by zero. Decimal divide. 


As well as technical misuse of instructions, 


a. Wrong compares 
D; Wrong branches 
C. Wrong calculations 


Operand two of CVD or CVB must be a double word. 


Analyze the programming problem well before you begin to code. 


Chapter 6 of Text 


Preventive programming is your best defense. 


Be careful about register use (very common mistake although simple, it could take a while 
before it is noticed). Write down what you are using the registers for in each routine. 
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If you have problems with external linkage, double check that the standard linkage was 
entered correctly. It is easy to reverse registers. 


As soon as you get the parameters in a subroutine, dump the registers so you can verify 
that you have the right parameters. 


Make sure registers used with DSECTs contain the right values. 


Remember to DROP all base registers when you're done with the DSECTs. 


Chapter 8 of Text 


Registers 1 and 2 are implicitly altered by the TRT instruction. 


When using a LH instruction the two leftmost bytes will be changed to the sign bit. 


Chapter 9 of Text 


A macro loop is different from an assembler loop. 


REMEMBER: do not mix assembler statements with macro processing statements. F or 


example 

AIF ('' NE '!') .FOUND 
. FOUND DS OH <---- WRONG 
. FOUND ANOP <---- OK 


Do not use R with the register number or use literals in a macro, because you do not 
always know if the programmer who is going to use this macro is using EQUREGS or 
LTORGs in his program. 
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SOCI - 


O 
O 


S0C4 - 


O 
O 


S0C6 - 


O 


O 


SOC7 - 


O 


SOC9 - 


O 
O 
O 


SOCB 
O 
O 


Some Common SOCx Abends 


Invalid operation code. 

You get this error when an attempt is made to execute an invalid operation code. 

Probable causes: 

- a missing branch instruction at the end of the routine. 

- code overwritten; compare the typed instruction at the abending address 
with the contents of storage in the dump at the abending address. 


Protection Exception. 


Attempt 1s made to refer to a storage not allocated to your program. 
Probable causes: 


- Invalid value in the base or index register due to any prior instruction. 


Specification Exception. 


With RX instructions: Address of the storage referred to is not on a full word 
boundary; 


Invalid value in the base or index register. 
With MP/DP: Invalid length specified for the receiving field. 


Data Exception. 
Attempting decimal arithmetic with a field contaming an invalid packed number. 


Fixed point divide exception. 
The quotient does not fit in the odd register of the even/odd parr. 
Attempt to divide by zero. 


This error occurs mostly because the even register does not contain the extension 
of the sign bit. 


- Decimal Divide Exception. 


Attempt to divide by zero. 
The quotient after DP does not fit in the specified area. 
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Chapter 6 - Overflow 


Overflow Discussion 


Overflow occurs when a number is computed that is too large for its value to be represented in 
its given space. An analogy to this is trying to put a size 8 shoe into a size 7 shoe box. The shoe 
would not fit, unless it was bent or damaged. When we try to put a number (in this case the shoe) 
into a reserved spot of storage (the shoe box), the number does not fit. The computer tries 
anyway, and will damage the number, causing it to change its value. For example, assume that 
you have a four bit register, with the highest bit, the one on the left, representing the sign bit. The 
registers could contain the following values. 


Value Bits in Register Value Bits in Register 
O OOOO =O 1000 
1 arele ml ait LOO 
2 OO1O =6 1010 
5 OO11 =) BO A 
4 O100 —4 TOO 
5 O101 = LO 
6 0110 ee 1110 
7 O111 = is Sea 


Notice that one more negative value is represented in two's complement form then there are 
positive values (7 versus -8). This is inherent whenever two's complement form is being used 
because zero is physically represented as a positive number, although logically, zero is neither 
positive nor negative. 


Let us add some numbers together in binary. All negative numbers are shown in two's 
complement. To the right of each example is the same computation using base ten arithmetic. We 
will note the carry bits from each addition, and show the decimal equivalent of the answer to the 
left of the answer. 


Binary Decimal Binary Decimal 
Carry Dits=-2 0002 LEOO 
OLOL ( 2) 1101 (=3) 
+0002 ( 1) +0100 ( 4) 
6 <- Q110 ( 6) 1 <- OOO] ( 1) 


The results are what we expected them to be. Let's try some more. 
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Binary Decimal Binary Decimal 


Carry DiLs=> 1010 O110 
TOL A (=) OO1O ( 2) 
0.0 (= @) +0111 ( 7) 
5 <- 0101 (= E) -7 <- 1001 ( 9) 


Notice that in both cases, the results are not what we expected. The values should have resulted 
in -11 and 9 instead of 5 and -7, respectively. Note also that the computed numbers -11 and 9 
cannot be represented in our given space, the 4 bit register. Thus, overflow has occurred. Could 
overflow occur when adding a positive number to a negative one? Why not? 


Detecting Overflow in Addition 


To detect overflow, we must look at the carry bits. The leftmost carry bit is sometimes referred 
to as the carry out bit. The second leftmost carry bit is called the carry in bit. Overflow occurs 
when the carry out bit does not equal the carry in bit. In simplest terms, if the two leftmost carry 
bits are not the same, overflow has occurred. In the first two examples, the two leftmost carry bits 
are 00 and 11, indicating no overflow. But in the second set of examples, the two leftmost carry 
bits are 10 and 01. This means that overflow has occurred and that the result obtained is invalid. 
Here are two examples of adding two fullwords together. 


INCORRECT METHOD CORRECT METHOD 


| 
| 
Carry out = Carry in | Garry Out <> Carry 17 
~. @ | \ 
(indicates 11000001 | (indicates 10101 OO0001 
no overflow) ABCD134C | overflow) A->1010 BCDIS4C 
4+A7213244 | +A->1010 7213244 
si a sso,‘ i se | pe a ri cs ait Ss ne Sn eas nae ae 
52EE 4590 | One mt! 2EE4590 


The first example show a common misconception that the carry in from the addition of B and 7 
is equal to the carry out from the addition of A and A which 1s incorrect. The second example 
demonstrates the correct way to check for overflow. The CARRY IN and CARRY OUT are 
applied to the SIGN BIT (leftmost bit of the leftmost hex digit). As demonstrated in the second 
example, the last hex digit has to be broken into bits and then a binary addition should be 
performed. To check overflow, the carry in and the carry out from the sign bit must be the same. 


Example 3 (a problem for the student to work); is there overflow’? 


ADEF4532 1010 DEF4532 
Coa 242 Se 1100 3455432 


If you can find the answer to this, then you should have a clear understanding of overflow. 
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Detecting Overflow in Subtraction 


Subtraction is done by adding the number of opposite sign. In symbols, A- B= A+ (-B). Thus, 
we reduce the problem of subtraction to that of finding the number of opposite sign (assuming that 
we have already mastered addition). 


A simple 2-step procedure can be used to find the number of opposite sign for (almost) any signed 
binary integer. There is only one situation in which it fails which we will discuss later. The 
two-step procedure 1s described as follows: 


l. Form a binary integer by reversing each bit in the original number. The result is called the 
"ONES’ COMPLEMENT" of the original number. 


2. Add 1 to the result of the first step. This gives what is known as the "TWO'S 
COMPLEMENT" of the original number and it is, in fact, the negative of the original 


number. 
Examples: 
ones’ add 
rz.) OO10 ---------- > 1101 -------- = 1410 (2) 
complement 1 
ones’ add 
(=) 1110 ---------- > 0001 -------- > 0010 (eZ) 
complement i 


The exception to the above rule (-8, since we cannot represent + 8 in our system) is illustrated 
next. 


complement dy 


Notice that adding | to 0111 (adding 2 positive numbers) in the above calculation gives a negative 
result. Our concept of overflow, as developed for addition, works again! 
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Example |: 


1234ABCD 
-“BCFCI2354 


+4 


Example: 2 


34DBCEFD 
“COB4ZI65C 


+3 


Examples of Fullword Subtraction 


1234ABCD 
—---> +(-BCFC1234) ---> BCFC1234 
—-------- 4303EDCB <--- ONES’ COMPLEMENT 
+] <--- TWO's COMPLEMENT 
4303EDCC <---- (-BCFC1234) 
OO0000 OL1LELO 
OO001 234ABCD 
—-—-> 0100 303EDCC ---> ANSWER 55389999 
Scere entetententantonton and no overflow! 
O101 5389999 
3 4DBCEFD 
—--~-> +(-CDB4563C) ---> CDB4563C 
-------- 324BA9C3 <--- ONES’ COMPLEMENT 
+] <--- TWO's COMPLEMENT 
324BA9C4 <---- (-CDB4563C) 
OO000 6 nae 
OO11 4DBCEFD 
—-—-> 0011 24BA9C4 ---> ANSWER 672778Cl1 
———— 0 and no overflow! 
6 a 6 72778C1 


4] 
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Chapter 7 - DC/DS Statement Examples 


This section contains examples of some of the data values which can be specified in a DC or DS 
instruction. Please read each one carefully and try to understand the generated object code. 


Data Type Codes 


Packed Decimal 
Zoned Decimal 


C = Character 

F = Fixed-point Fullword 
H = Fixed-point Halfword 
A = Address 

B = Binary 

xX Hexadecimal 

P 

Z 


DC Statement Format 


label DC mTLn'nominal value' 


m Duplication factor of the data. If omitted then the assembler assumes a duplication 
factor of one. 


st Data Type Code 


Ln Length of the data. 
If omitted then the assembler will default to the number of bytes in the nominal 


value. 

If the nominal value is larger or smaller than specified, padding or truncation will 
occur. 

If used with F,H,D,A data then the alignment boundary will not be in effect. 


NOTE: Duplication factor does not affect the maximum length of each data element. 


DS Statement Format 
label DS mTLn'optional nominal value' 


2 The format of the DS operand is identical to that of the DC operand; exactly the same 
subfields are used and are written in exactly the same sequence as they are in the DC 
operand. 
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< Unlike the DC instruction, the DS instruction causes no data to be assembled. 
Therefore, you do not have to specify the nominal value of a DS instruction operand 


and if it is specified, it is ignored. For this reason, 


O It is BEST to NEVER include a nominal value in a DS instruction 
= The DS instruction is the best way of symbolically defining storage for work areas, 


input/output buffers, etc. 


® Pay attention to the DS statements marked *NOTE in the following examples. 


TYPE: © 


MAXIMUM LENGTH: 256 BYTES 
STORAGE FORMAT: Characters 
PADDING / TRUNCATION: Right 


PADDING : Blanks 


Character Data Examples 


LOC OBJECT CODE STMT SOURCE STATEMENT 

1 * 

2 * TYPE C DATA 

3 * 
O00000 FSFOF4F/F3F8 4 DC Cr 204730" 
OO0O0006 FILFSF/7 5 DC Chas’ 251743035" 
OO0009 F4F5F640 6 DG CL4'456' 
OOOOOD 6O0F8F7 ] DC Cls 5 353°" 
OO00010 60F5F6 8 DG: Ch3" 56.404" 
000013 FIF24B 9 DC Ch3? 12.345" 
000016 60F14BF34040 aes DC C67 =2...3°" 
OO001C FOFIL a DC CU” 
OOOQO01E C150C2 LZ DC CL3'A&&B' 
000021 D1C4C8E4 13 DC CL4'DEFGH' 
000025 C4D9C6C55040 14 DC CL6O'DRFE&&' 
OO0O002B bis. DS CLO 

*NOTE: Special characters ' (single quote) and & (ampersand) must be doubled in a DC 


statement if they are to be generated. 
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Fixed-Point Fullword Data Examples 


TYPE: F 

MAXIMUM LENGTH: 4 BYTES 
STORAGE FORMAT: Binary 
PADDING / TRUNCATION: Left 
PADDING : Binary Zeros 


LOC OBJECT CODE STMT SOURCE STATEMENT 
52 = 
53 * TYPE F DATA 
54 * 
OO0000 OOODODOVOVDOC 5 ee. DC | ieee 
OO00004 FFFFFF6A 56 DC P= 150" 
OO00008 OQOOODODVDVDOVO oe DC A eae © 
OOO000C OOOODQVOOCQOO00000C ees DC Ze ae 
O00014 O0007D00 ORS, DC EF" 32000:" 
QO00018 OOO0C 60 DG FiZ Lz" 
00001C 61 DS F 
* The location counter will start on a fullword boundary automatically except when L 


(length modifier) is used with a data type of F. 


* A fullword boundary address in hex will end with O, 4, 8, or C 


Fixed-Point Halfword Data Examples 


TYPE: H 

MAXIMUM LENGTH: 2 BYTES 
STORAGE FORMAT: Binary 
PADDING / TRUNCATION: Left 
PADDING : Binary Zeros 


BOC OBJECT CODE STMT SOURCE STATEMENT 

oi. * TYP. H DATA 

o2 * 
OO0000 ODOC G3 DC ae Ole 
OO00002 FFO6A 64 DC Be bo 
O00004 OO0O0O0 ope. DG a" 
OO0006 DOOCODODNDC 66 8, @ ae ae BAe 
OOQOOO0A 7DO0 67/ DC eps yO ee 
OOO000C OD 68 DC Bu * 13° 
OOOOQ0E 69 DS H 
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Address Data Examples 


TYPE: A 

MAXIMUM LENGTH: 4 BYTES 
STORAGE FORMAT: Binary 
PADDING / TRUNCATION: none 
PADDING : none 


LOC OBJECT CODE STMT SOURCE STATEMENT 

77 * 

78 * TYPE A DATA 

ta 
OOO00D8 80 SAVE DS Clb? 
OOOO0E4 OO0OOO0O000S5S 3.1. 18 1@ PAS) 
OOO0E8 OOO000D8 SZ DC A (SAVE) 
OOO0EC OODDODD0000000000 25 De A(0,0) 
OO000D4 OODDDD00000000D800000005 84 DE A(0,5AVE, 5) 
OOOOEO 000008 85 DC AL3 (8) 
OO00E3 010203 8 6 DC AL1 (1,2, 3) 

* The location counter will start on a fullword boundary automatically except when L 


(length modifier) is used with data type A. 


Binary Data Examples 


TYPE: B 

MAXIMUM LENGTH: 256 BYTES 
STORAGE FORMAT: Binary 
PADDING / TRUNCATION: Left 
PADDING : Binary Zeros 


LOC OBJECT CODE oTMT SOURCE STATEMENT 
Za °° 
Za. * TYPE B DATA 
Zo = 
OOO0000 O5 26 DC BrOLGL- 
OOO0001 0057 24 DC BiZ*OUL0L01 2." 
O00003 O3A2F3 20 DC BES’ 11 LOL000LOLTILILZO0OLL" 
OO0006 Ol 29 De B* Us." 
OO00007 Ol 30 DC Bit “O1* 
OO0008 OOOI1 31 DC Big 
OOOOQ0A O7 32 DC Bigk” OL 
OOQOOQOB 55 33 DC Bid "O12 201010101" 














Hexadecimal Data Examples 


TYPE: X 

MAXIMUM LENGTH: 256 BYTES 
STORAGE FORMAT: Hexadecimal 
PADDING / TRUNCATION: Left 
PADDING : Hexadecimal Zeros 


LOC OBJECT CODE STMT 
Lo. = 
ie; 
Lae 

OO0000 123456 18 
000003 ABCD i 
O00005 001234 20 
000008 345678 Z 
OOOO00B O00001D3 oe 
OOOOOF O1D3 ae 


SOURCE STATEMENT 


TYPE X DATA 


» eae AAG! oy om 
XL2'ABCD' 

> VS Balt Ae oa 
Ais 2545016" 
XL4'1D3' 

A DS? 





Packed Decimal Data Examples 


TYPE: P 

MAXIMUM LENGTH: 16 BYTES 
STORAGE FORMAT: Packed Decimal 
PADDING / TRUNCATION: Left 
PADDING : Packed Decimal Zeros 


LOC OBJECT CODE STMT SOURCE STATEMENT 

Zo 

a TYPE P DATA 

oak 
OO0000 567C 32 DC PhZ*1LoGT* 
000002 0345677C 33 DC P'34567/7' 
OO00006 67891C 34 DC Pio’ 36/591" 
000009 OO000567C 30 DC PL4'567' 
OOOO00D 00567D 36 DC Pius -26/" 
000010 56789C a4 DC Poo 205 100" 
000013 56762D 38 DC Pho =90. 1/62" 
000016 OOI1C a2 DC P*O1" 


Zoned Decimal Data Examples 


fig id Deer 4 

MAXIMUM LENGTH: 16 BYTES 
STORAGE FORMAT: Zoned Decimal digits 
PADDING / TRUNCATION: Left 
PADDING : Zoned Decimal Zero (X’ FO") 


LOC OBJECT CODE SIMT SOURCE STATEMENT 

40 * 

41 * TYPE Z DATA 

42 * 
000000 F6C/ 43 DC fe Loot” 
000002 F3F4F5F6F7/C/ 44 DC Zi 2a007 4" 
000008 F8FI9CI1 45 DC Zigs SO 1671 
OOO000B FOFSF6C/7 46 DC ZL4'567/7' 
OOOOOF FSFO6D/ 47 DC ZG3 "2607" 
O00012 FIFSC? 48 DC TiS DO. Too 
000015 FIJEsC? 49 DC Zsa V50< 157" 
000018 FSF6F7F8D9 50 DC Z'=56.789" 
OO0001D FOCI ee DC Ze OA" 
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Chapter 8 - Decimal Conversion 


To facilitate numeric input/output, ASSIST accepts the commands XDECI (eXtended 
DECimal Input), and XDECO (eXtended DECimal Output). XDECI can be used to scan input 
cards for signed or unsigned decimal numbers and convert them to binary form in a general 
purpose register, also providing a scan pointer in register 1 to the end of the decimal number. 
XDECO converts the contents of a given register to an edited, printable, decimal character 
string. 


Both instructions follow the RX instruction format, as shown: 
XDECI R,,D,(X,,B.) XDECO R, ,D, (X,,B.) 


where R, is any general purpose register, and D, (X,,B,) 1s an RX-type address, such as 
LABEL 0(4,5) LABEL+3 (2) 


XDECI 


XDECTI is generally used to scan a data card read by XREAD. The sequence of actions 
performed by XDECI 1s as follows: 


I Beginning at the location given by D, (X,,B,), memory is scanned for the first 
character which is not a blank. 


2. If the first character found is anything but a decimal digit or plus or minus sign, 
register | is set to the address of that character, and the condition code is set to 3 
(overflow) to show that no decimal number could be converted. The contents of R, are 
not changed, and nothing more is done. 


a From one to nine decimal digits are scanned, and the number converted to binary and 
placed in R,, with the appropriate sign. The condition code 1s set to 0 (0), | (-), or 2 
(+ ), depending on the value just placed in R,. 


4. Register | is set to the address of the first non-digit after the string of decimal digits. 
Thus R, should not usually be 1. This permits the user to scan across a card image for 
any number of decimal values. The values should be separated by blanks, since 
otherwise the scanner could hang up on a string like -123*, unless the user checks for 
this himself. I.e., XDECI will skip leading blanks and signs but will not itself skip 
over any other characters. 
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a. During step 3, if ten or more decimal digits are found, register 1 is set to the address of 
the first character found which is not a decimal digit, the condition code is set to 3, and 
R, is left unchanged. A plus or minus sign alone causes a similar action, with R1 set to 
the address of the character following the sign character. 


6. In summary, the condition code is set to 
Q - if converted number was 0 
] - if converted number was < 0 
2 - 1f converted number was > 0O 


3 - if an invalid character is found, or the number was too long (or short) 


And RI will pomt to the blank after the last digit of the number. 


XDECI Examples 


The first example will demonstrate how to extract two numbers from a record in storage. 
The two numbers to be extracted are 1234 34 in the following input record: 
INPUT DC CL15' 1234 34 
This is what it will look like in storage: 
40F1F2F3 F4404040 F3F44040 404040....... 
Convert the first number to binary: 
XDECI 5,INPUT 


Now RI points at the blank (40) after 4 (F4) from the 1234 number. In order to pick up the 
next number the scan must start at the point where it last stopped. 


XDECTI 6,0(,1) (This will convert the next number to binary) 
The same logic can be used in a loop to pick up an unknown number of integers. After the 
first number has been converted, all the rest numbers will be picked by coding 


XDECI R:,0(,1) because after every conversion R1 will point to the blank immediately 
following the number last converted (that is where the scan should start). 
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Another example of XDECI. 


OOOQQLBA INPUT DS CL80 


| 

| Let's say that this is what is in the input 
| buffer. 
| 
| a 


> FILF4404040F2F0404060F1FO40F94040F0404040...... 
| 
OOOO00Z0A SCANSTOP DC €*?" <--- THIS IS THE INVALID CHARACTER TO 


i“ SrOP TERE. SCAN 


Now, perform an XDECI on each of the five numbers in the input buffer. 


XDEGCI SO; INeuUL GET THE FIRST NUMBER FROM THE INPUT BUFFER 


* R5 ----> OQOOQOOQOO0E CC = 2 
* Rl -—----> QOOOOLBC 
* 

MDECL 5,70 '(;,4) GET THE NEXT NUMBER 
* R5 ----> 00000014 CC = 2 
* R1 ----> QOOOOOICL 
* 

DEC. Oy Ute.) GET THE NEXT NUMBER 
* R5 ----> FFFFFFF6 CC = l 
* R1 ----> QOOOO1C6 
* 

Mec Opts GET THE NEXT NUMBER 
* R5 ----> 00000009 CC = 2 
* R1 —----> OOOO001C8 
* 

MDRCL 32-0640 GET THE NEXT NUMBER 
* R5 ----> 00000000 CC = 0 
* R1 ----> QOOOOI1LCB 


There are two ways to determine the end of input in your input buffer. The first is knowing 
the amount of numbers per input buffer read in and only performing that many XDECIs on the 
input buffer. The second is setting an invalid character at the end of your input buffer and 
quitting when the condition code from your XDECTI isaCC= 3. 


Following the sequence above we now attempt (and fail) to extract a sixth number from the 
input record, using the second method above to signal the end of the input record. 


XDECI 5,0(,1) TRY TO EXTRACT THE NEXT NUMBER IN THE: INPUT BUPPoR 


Re Sosa > 00000000 CC = 3 
Ro ease > O0O0O00020A 


Remember that the contents of R5 will not change if an invalid character is detected. 
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The following example shows how to process an arbitrary number of input records, each of 
which contains an arbitrary number of values: 


XREAD INPUT2, 80 


LOOP IL BC B'Q100', EOF END OF FILE 
XDECI 5,1 NPUTZ GET FIRST NUMBER 
LOOP2 BC B'QQO1', BOREC CK FOR INVALID CHARACTER 
> WHICH INDICATES END OF INPUT 


process the first number 


ADECL Df 0, 1) GET NEXT NUMBER 


BC Se ee ta 2 BRANCH UNCONDITIONALLY TO LOOP2 

EOREC DS OH 
XREAD INPUT2,80 READ NEXT RECORD 
BC B' 1121"; WOOP! BRANCH UNCONDITIONALLY TO LOOP1 

EOF DS OH 

INPUT2 DS CL80 
DC ere 

NOTE: XDECT is not at all linked to XREAD. You can convert any number from 


character to binary by providing proper address. It is mostly used with XREAD 
because the data is generally specified in character format and needs to be 
converted (numbers only) to binary format for calculations. 


NOTE: Never use RI as the receiving field on XDECI instruction. To be extra careful. 


expecially at the beginning of the semester, DO NOT use R1 for anything else 
if XDECI is being used in the program. 
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XDECO 


XDECO converts the value in R, to printable decimal, with leading zeroes removed, and a 
minus sign prefixed if needed. The resulting character string is placed right-justified in a 
12-byte field beginning at address. It can then easily be printed usmg an XPRNT 
instruction. The XDECO instruction modifies NO registers. 


D, (X,,B,) - must be a 12 byte field where you want to store the converted number 
(Normally on the print line). 


XDECO Examples 


XDECO 5,SUM R5 contains OOQOQOQOQOOA 

PLINE DC C'O' <-- DOUBLE SPACE CONTROL CHARACTER 
DG CL22' THIS IS THE ANSWER : ° 

SUM DS Cihii2Z 
DG Clao- 4223" 


After XDECO SUM will contain 
40 40 40 40 40 40 40 40 40 40 F1 FO 
When the PLINE is ready to be printed it should look like this 
THIS IS THE ANSWER : LO ti4 3 
WARNING: If the field is defined to be fewer than 12 bytes as in the following 


example, then the next field will get overwritten. In this case, we will 
overwrite three of the exclamation marks. 


XDECO 5,SUM R5 contains 00000020 

PLINE DC Cr! <—-—- TRIPLE SPACE CONTROL CHARACTER 
DG CL22' THIS IS THE ANSWER : ' 

SUM DS CL8 
DC Ciso* 3.587 


After XDECO SUM and 4 characters of the next field will contain: 


40 40 40 40 40 40 40 40 40 40 F3 F2 


THIS IS THE ANSWER : 32! 
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Chapter 9 - A Complete Program 


Let us write a program starting from the initial requirement. You will benefit by careful study 
of each statement, and you should ask your instructor or TA to explain anything you don’t 
understand. 


Problem: Read twenty integers, one by one, add all the positive numbers (> 0) and find 
their average. 


Step1: Write down the logic, i.e. how would you do it if there was no computer. 


Get the numbers one by one, if they are higher than 0 add them to accumulator, 
increment the positive number counter. Once all done, calculate the average. 
You will need an accumulator, a loop counter, a positive number counter. 


Step 2: Write the pseudocode: 


LOOPCNTR=0 
POSCNTR=0 
POSACCUM=0 
READ NUM 


DO WHILE LOOPCNTR < 20 
CONVERT NUMBER TO BINARY FORMAT 
ITF’ CONVNUM > 0 
POSACCUM = POSACCUM + CONVNUM 
POSCNTR = POSCNTR + 1 
ENDIF 
LOOPCNTR = LOOPCNTR + 1 
READ NEXT NUMBER 
ENDDO 


AVERAGE = POSACCUM / POSCNTR 
CONVERT AND PUT NUMBER ON PRINT LINE 
PRINT AVERAGE WITH PROPER MESSAGE 


= 





Step 3: 


Start the process of writing the Assembler code. In this step we will decide 


which instruction will be used for the corresponding line of pseudocode. 
Registers can be used for accumulators and counters: 


LOOPCNTR=0 
POSCNTR=0 
POSACCUM=0 
READ NUM 


DO WHILE LOOPCNTR < 20 
CONVERT NUMBER TO BINARY FORMAT 
ITF CONVNUM > O 
POSACCUM = POSACCUM + CONVNUM 
POSCNITR = POSCNTR. + 2 
ENDL 
LOOPCNTR = LOOPCNTR + 1 
READ NEXT NUMBER 
E;,NDDO 


AVERAGE = POSACCUM / POSCNTR 
CONVERT AND PUT NUMBER ON PRINT LINE 
PRINT AVERAGE WITH PROPER MESSAGE 


Necessary storage would be: 


INPUT DS 
PLINE DC 
DC 
DC 
PRICNIR: -Ds 
DC 


PRTAVG DS 
TWENTY DG 
ZERO DC 
ONE DC 


CL80O 

Sh me 

GaiZe” * 
C'Average of' 
CL12 
C'positive numbers is' 
CUZ 

aaa Oe 

EQ" 

BY a." 


Carriage Control 
Blanks 
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storage of counter 


(SR) 
(SR) 
(SR) 
(XREAD) 


(C and BC) 
(ADEC TL) 

(C and BC) 
(AR) 

(A) 


(A) 
(XREAD) 
(BC) 


(DR) 
(XDECO) 
(XPRNT) 





Step 4: Now write the final program 


dee KKK KK KK KKK KKK KKK KKK KKK KKK KKK KKK KKKKKKKKKKKKKEKKKEKKKKRKRKKKKKEKKEKE 


* * 
* NAME : EXAMPL * 
* , * 
~ FUNCTION : TO READ 20 NUMBERS AND FIND THE AVERAGE OF ALL * 
x NUMBERS GREATER THAN O * 
x * 
es INPUT .* 20 RECORDS, EACH CONTAINING AN INTEGER * 
* * 
* OUTPUT - THE AVERAGE PRINTED WITH APPROPRIATE MESSAGE * 
* * 
am ENTRY CONDITIONS : NONE * 
* * 
% EXIT CONDITIONS >: NONE * 
* * 
* ALGORITHM 
* * 
* 1.  LOOPCNTR=0 
* POSCNTR=0 * 
* POSACCUM=0 * 
* READ NUM * 
* Zé DO WHILE LOOPCNTR < 20 * 
* CONVERT NUMBER TO BINARY FORMAT x 
x a. ITF CONVNUM > O * 
* POSACCUM = POSACCUM + CONVNUM * 
* POSCNTR = POSCNTR + 1 * 
* ENDIF x 
* LOOPCNTR = LOOPCNTR + 1 * 
* READ NEXT NUMBER * 
* ENDDO x 
as 4. AVERAGE = POSACCUM / POSCNTR * 
* CONVERT AND PUT NUMBER ON PRINT LINE * 
* PRINT AVERAGE WITH PROPER MESSAGE * 
* * 
* NOTES : THIS IS AN EXAMPLE AND IT DOES NOT USE ALL THE * 
* EFFICIENT INSTRUCTIONS, SINCE IT IS TO BE REFERRED * 
* FARLIER IN THE SEMESTER * 
* * 
EK K KKK RK KKK EK RK KK KKK KKK KKK K KEK KEKE KKK EKER ER EERE EKRKEREEERKKEEKE 


TITLE 'A SAMPLE PROGRAM’ 
EXAMPL Conc 


* 


*STEP 1 

* 
USING EXAMPL,15 TELL ASSEMBLER R15 IS AVAILABLE 
SR 2u8 LOOPCNTR = 0 
SR 40 POSACCUM = 0 
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OR 4,4 POSCNTR = O 














SPACE 1 GIVES ONE BLANK LINE 
XREAD INPUT, 80 READ RECORD 
* 
*STEP 2 
* 
LOOP1 C 2, TWENTY DO WHILE 
BC B'1010', ENDFILE (LOOPCNTR < 20) 
XDECI 5,INPUT CONVERT TO BINARY 
* 
*STEP 3 
* 
IF. 2 5, ZERO IF 
BC B'1100',NOTHI (CONVNUM > 0) 
AR aan POSACCUM=POSACCUM+ 
* CONVNUM 
A 4, ONE POSCNTR=POSCNTR + 1 
NOTHI DS OH ENDIF 
A 3, ONE LOOPCNTR=LOOPCNTR + 1 
XREAD INPUT,80 | READ RECORD 
2 LOOP1 ENDDO 
ENDFILE DS OH 
* 
*STEP 4 
* 
LR 7,3 SAVE POSACCUM 
M 6, ONE EXTEND SIGN BIT 
DR 6,4 AVERAGE=POSACCUM/ POSCNTR 
XDECO 5,PRTAVG PUT AVERAGE ON PRINT LINE 
XDECO 4, PRTCNTR PUT CNTR ON PRINT LINE 
XPRNT PLINE,74 PRINT PRINT LINE 
XPRNT PLINE,1 ADVANCE PAGE 
BCR B'1111',14 RETURN TO OPERATING SYSTEM 
* 
EJECT 
LTORG 
TITLE 'STORAGE FOR THE SAMPLE PROGRAM’ 
INPUT DS CL80 
* 
PLINE DC on Fea ae CARRIAGE CONTROL AND SPACES 
DC C'AVERAGE OF' MESSAGE 
PRTCNTR DS CL12 STORAGE FOR COUNTER 
DC C'POSITIVE NUMBER IS' MESSAGE 
PRTAVG ODS i STORAGE FOR TOTAL 
* 
TWENTY DC F'20' CONSTANT 
ZERO DC FF? 9? CONSTANT 
ONE DC F'l' CONSTANT 


END BEXAMPL 
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Chapter 10 - The Load Address Instruction 


The Load Address (LA) instruction is in the RX format: 


label LA R, ,D, (X,,B.) 


= Execution of this instruction causes the address given by D, (X,,B,) to be calculated 
and placed in R,. 


* An address is only three bytes (24 bits) long, so the leftmost byte of R, is set to 00. 
* You must also remember all the other rules governing the address calculation: 
O RO is not considered in address calculation 


O The address 1s only three bytes (fourth byte, the leftmost byte, is X'00'). 
For example, if RS contains 12345678 
and R6 contains 34567890 
then the second operand of 
LA 3;,30(6,5) 


will be calculated as an address in the following way: 


LZSa 9076 
F54501590 


OO8ACF26 (Note that the resulting high-order byte is zero!) 
So, after execution R3 will contain OO8ACF26. Likewise, 
LA 3,0(0;,5) 


will put 00345678 + 0O + O or 00345678 in R3. 


S7/ 








The Difference Between LA and L 


As mentioned above LA puts the address itself in the receiving register whereas L (load) picks 
up the four bytes at the specified memory address and put those bytes in the receiving 
register. 


LOC OBJECT CODE 
OOOQOOEOQ OQ0000014 WORD DC P20" 
Thus, LA 3,WORD will put the address of location WORD in R3, so R3 will contain 


OOOOOOEDO after this instruction has been executed. 


On the other hand, L 3,WORD will get the contents of the four bytes of memory 
beginning at location WORD and put them in R3, so R3 will contain 00000014 after this 
instruction has been executed. 


What would be in R2 after the following two instructions have been executed??? 


LA 2 ,WORD 

L 2,0 C2) R2 = 
All RX instructions are encoded as OORXBDDD, so we have three hex di gits (DDD) available 
for displacement. This means that the maximum displacement is X’ FFF’ , which is 4095 
decimal (the maximum possible displacement which can be coded on any instruction). 


Another common mistake with LA is the idea that the address of a register can be loaded into 
another register. Thus, 


IA 3,5 < --- The misconception is that the address of R5 will be loaded 
into R3. But, there is no address for a register. Furthermore, just 
because we have "R" in front of "5" it does not become a 


register. In this case LA R3,5 will produce the same result as 
LA R3,R5. 
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Common Uses of Load Address 


l. To get the memory address of a field. 
2. To set a register to any integer value between 0 and 4095 
LA 2,10 - will put 0000000A in RS because there are no base and/or index 


registers; thus the displacement will be 10. 


The same thing could also be done by L 5,=F'10" but this takes 8 bytes (4 for 
literal and 4 for instruction) and thus is less efficient (even though clearer). 


2. To increment a register by any integer value between 0 and 4095 


LA 5,20(,5) will increment R5 by 20. The same thing could be done by using the 
instruction A  5,=F'20' which would be clearer but not as efficient. 


WARNING: Remember that address calculation drops the leftmost byte, so if the value in the 
register 1s negative or a big positive number then you must NOT use LA for 
incrementing the contents of a register. 


Assume that R3 contains 12345678 


What will be in R3 after the following instruction has been executed? 


LA S73 Cpa) R3 = 





SI 











Chapter 11 - Memory Dumps 


Note: Also, see Chapter 11 of Text 


Dump Contents 


If your program ABENDs (ABnormally ENDs), ASSIST generally will provide you with a 
memory dump which can help you isolate the reason for the ABEND. The only instances in 
which you will not get a dump are those in which your job exceeds the time limit (no time 
remains to generate the dump), or the job generates more than the number of lines allowed 
(2000 is the default maximum number.) 


The information available to you 1n a dump includes: 


The contents of the PSW. See your yellow card and/or page 498 of your text for a 
description of a BC mode PSW. You should learn to be able to extract from the PSW 
any of the information which it contains. 


The completion code. See your yellow card for a listing of program interruption 
codes - also, appendix D of your text gives a good explanation of the more commonly 
encountered completion codes, along with various programmer errors which can cause 
those types of interrupt. 


A trace of the last few instructions executed. 
A trace of the last few branch instructions executed. 


Contents of the 16 general purpose registers at the time of the ABEND. Since you 
are not going to be using the floating point registers, you can ignore them. 


The contents of user storage (the portion of main storage used by your program and 
its save areas) is dumped in hexadecimal. Each line contains 32 bytes of storage. In the 
left-hand margin you will find the address of the first of these 32 bytes (LOC.) On the 
right-hand margin you will find (between two *s) a translation into character form, 
where alphabetic and numeric characters and blanks are identified whenever a byte 
contains the character's encoded form a period 1s printed to represent any other byte 
values. 
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When your program ABENDs, you should be able to answer questions such as: 


I 


Z, 


What was the reason for the ABEND (interruption code)? 
What does that interruption code mean’? 

What was the last instruction executed? 

Did the registers contain the "right" values? 


Were the contents of user storage correct? 
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Dump Assignment 1 


Type in and run the following program: 


DUMP1 CSECT 
USING DUMP1,15 ESTABLISH A BASE REGISTER 
L 1 ,ONE LOAD THE FIRST NUMBER INTO RI 
L 2, TWO LOAD THE SECOND INTO R2 
AR pe ADD THE TWO NUMBERS 
ST 1, THREE SLORE. THE. RESULT 
XDUMP THREE, 4 DUMP THE RESULT 
BCR Bee ye RETURN TO CALLER 

* 

ONE DC F'64' FIRST NUMBER 

TWO DC F’.32Z' SECOND NUMBER 

EOFFLAG DC cra? A FLAG SAVE AREA 

THREE DS Ch4' ! SUM OF THE TWO NUMBERS 


END DUMP1 


After running the above program you should be able to answer the following questions: 


LE; 


Z. 


10. 


What is the address of the next instruction which will be executed? 
What is the address of the instruction that caused the abend? 

What type of error occurred? 

What actually causes this error? 

Correct the error by rewriting the section of code that caused it. 
What is the contents of register 1 in decimal? 

What does the value in reg 1 represent at the time of ABEND? 


Why is the LOC address of the storage area with the label ONE on it 000018 when the 
branch statement before it whose LOC address is 000014 only takes up 2 bytes? 


What are the contents of the two bytes of user storage starting at address 000016? 
What do they represent? 


What are the contents of the byte saved at address 00001B? Does this byte represent the 
first byte of a full word? 
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it 


IZ. 


La: 


14. 





Which of the following are synonyms for the same length? [There may be more than 
one group of synonyms. | 


a. 6 hex digits” d. 32 bytes g. fullword Ve 64 bits 
b. 4 bytes S. 32 bits h. byte k. halfword 
G, 8 hex digits f. doubleword 1. foot l. meter 


If the dump program error were corrected, what value would the storage area at label 
THREE contain? 


What two instructions have you worked with which cause data conversion to take 
place? 


What is the decimal equivalent of hex 0002BA14? 
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Dump Assignment 2 


Type in and run the following program: 


DUMP2 CSECT 
USING DUMP2,15 
LA 2, TABLE 
SR 3,3 
XREAD DATA, 80 
LOOP1 BM ENDLOOP1 
XDECI 4,DATA 
ST 4,0(2,3) 
LA 3,4(,3) 
XREAD DATA,80 
B LOOP1 
ENDLOOP1 SR 3,3 
LA 7, TABLE 
LA 5 , TABEND 
LOOP2 CR 2,5 
BE ENDLOOP2 
8 6,0(,2) 
ST 6,0(,7) 
. 7,4(,7) 
LA 2,4(,2) 
B LOOP2 
ENDLOOP2 BR 14 
LTORG 
DATA DS CL80 
TABLE DC 30F'-1' 
TABEND DS Ox 
END  DUMP2 
0 
1 2 
50 


32 24 19 62 
LS 26: Feo 
987 654 321 


Using the results from the program, answer the following questions: 


l. What was the interruption code? 
Zz What instruction caused the program to abend? Why? 
a What was the condition code at the time of the ABEND? 
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4 How many table entries were built? How did you figure this? 


>. What is the return address to the calling routine? Where did you find this? Does your 
answer really make any sense? 


6. What are the contents of register 7? 
qe Was any object code changed by this program? If so, for which instructions? 
8. Explain why the program ABENDed. 
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Chapter 12 - The ORG Instruction 


The ORG instruction 1s used to alter the value of the location counter. 


ORG addr 
or 


ORG 


In some ways it is similar to the REDEFINES clause in COBOL. 


a With an address specified, ORG changes the location counter to the location counter of 
addr. 
$ Without an address, ORG changes the location counter to the next available unused 


location in the program. 


OO0120 CARD DS CL80O 
ORG CARD 
OQ00120 SON DS CLI 
VO0LZ9 TRANCODE DS & 
OQOO1L2ZA ADDTRAN DS UC 
OOO12ZA NAME DS CiZ0 
OO0O013E ADDRESS DS CiiZv0 
ORG ADDTRAN 
OOO12ZA MODTRAN DS Cig 
OQO013E ADDRESS DS di. 
ORG MOD'TRAN 
00013E PARTNO D> 20 
ORG MODTRAN 
QOOO01L3E QUANTITY DS CLES 
ORG 
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Another Example: 


Let us say the input can be in three different formats: 


Part definition 1- 5 Part # 
6 Code P 

7J-l1l Number in stock 
12-80 Unused 


Order 1- 5 Part # 
6 Code O 

7-11 Number ordered 
12-80 Unused 
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New Stock 1- 5 Part # 
6 Code S 

7-11 Number received 
12-80 Unused 


Instead of using three different input areas, we can use only one input area and org as follows: 


CARD DS CL8O0 

ORG CARD go back and redefine 
PARTNUM DS CLS Same in all cases 
CODE DS c 


INSTOCK Dos CL5 
ORG INSTOCK 
ORDERED DS Cho 
ORG INSTOCK 
RECEIVED DS CLS 
ORG next available location 
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Chapter 13 - Decimal Instruction Examples 


Important: Every DC/DS field has a implicit length attribute which the assembler will use 
in the absence of an explicit length; most of the examples in this section take 
advantage of this fact. Nonetheless, there are times when an explicit length 
should be used to override the implicit length; your instructor will explain this. 


PACK 

Example 1: 

PACK PACDATA, CHARDATA 
CHARDATA DC Cli? * 1567392" = X’FLIFSF6F7F3F9 F2' 
. bt td tt & 
PACDATA DS PL4 15673 9 2F = X’1567392F’ 
Example 2: 

PACK PAREA, ZONEDATA 
ZLONEDATA DC ZL9'47/7653! = X’ F4F7F6F5 C3' 
‘i 1 | | | % 
PAREA DS PL4 padding ---> 00 4765 3C ---> X’0047653C’ 
Note: Remember that the PACK and the UNPK instruction are not themselves 


“packed decimal” instructions and do not require that the operands be valid 
packed decimal data fields. 


More examples: 


FLD1I DS PL3 
FLD2 DG Zo Lae = X’FLF2F3F4C5' 
FLD3 DC Ci = X’FILF2F3' 
FLD4 DC Z'1234506' = X’PFIF2ZEF3F4F5C6' 
PACK FLD1,FLD2 FLDIL = X’12345C’ 
PACK FLD1,FLD3 FDL = X* OOLZ3F* 
PACK FLDI1,FLD4 FLDL = X’23456C’ 
PACK FLD2,FLD2 FLD2 = X’000012345C’ 


Note: Rules for overlapping fields permit the final example above to work, but this is not a 
recommended practice except when the fields are the same single byte. 
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Example: 

UNPK 
PNAME DC 
ZNAME, DS 


ZNAME2 DS 
ZNAME 3 DS 


UNPK 


UNPK 


More examples: 


FLDI1 De 

FLD2Z DS 

FLD3 |B) 

FLD4 DS 

pe dB ea. DC 
UNPK 
UNPK 
UNPK 
UNPK 





UNPK 


ZNAME, PNAME 


P’14263' = 142 6 3C 
| | [| [| & 
ZLoO = FIF4F2F6 C3 
ZL6 
ZL4 
ZNAME2,PNAME ----> ZNAME2 = X’ FOFLF4F2F6C3' 
ZNAME3,PNAME ----> ZNAME3 = X’ F4F2F6C3' 
Peo 
7a tive 
/AaakS > bo po soe or a 
Cleo 
P'123456/89' 
FLD2,FLDI FLD2 = X’FLIF2Z2F3F4C5" 
FLD3,FLDI FLD3 = X’FOFLF2F3F4C5' 
FLD4,FLDL FLD4 = X’F3F4C5' 
PODZ; FLD FLD2 = X’FSFOF/F8C9'! 
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EXAMPLES: 


ly Ey B 


TOTAL 
ACCUM 


More Examples: 


FLD1L 
FLD2 
FLD3 


LAP 


DC 
DS 


LAP 
LAP 


LAP 


DC 
DG 


LAP 
BZ 


DG 
Be 
DC 
LAP 
LAP 
LAP 
LAP 
LAP 
LAP 


ZAP (Zero and Add Decimal) 


FLD(5),FLD ZAP a field into itself 


to make it larger. 


PL4'123456' 0123456C ----> 000123456C 

P Spare byte for expansion 

FLD(3),FLD But not to make it smaller - Data 
exception (Works from right to left) 


NUM (2),=P'1000' Overflow - 1000 can't be 
represented in 2 bytes 


TOTAL, ACCUM(3) Data exception - ACCUM for a 
length of 3 is not valid. 


PP’ iL00" LOOC 

aaa OF 0 Z00C 

NUM, NUM If NUM = O, get out of loop 

ENDDO N.B. Doesn’t change NUM, just sets CC 
Pp =69" = X’069D’ 
P’ 4932" = X’04932C’ 
P’34218' = XK’ 34218C’ 

FLD.» LDS FLD1I = X’218C’ CC=3 
FLD2,FLD1 FLD2 = X’000609D’ CC=1 
PLDZ,;f isp FLD2 = X’34218C’ CC=2 
FLD1,FLD1 FLD1 = X’069D’ CC=1 
FLD3,=P'O' FLDL = X’OQ0O000C’ CC=0 
FLD3,=2Z'Q' *DATA EXCEPTION* 


Note: ZAP is most often used to change the size of a packed decimal number, both for EDit 


FLDI 
FLD2 


ZAP 
CVE 
LC 
DS 


and (especially) for CVB: 


FPiDZ,;2LDL FLD2 = X’Q00000000000123C’ 
RZ, D2 R2 = X’0000007B’ 

aie oe FLDIL = X’123C’ 

D 
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AP (Add Decimal) 


EXAMPLES: 
AP FiDl, FiD241 (1) 100C 
OO2Z00C 
acd Data exception, 20 not 
valid packed number 
AP FLDI1,=P'2' LOOC Can use a literal 
ZG Takes needed length 
FLD ==<==—> LOZC 
AP FLD1,=P'999' LUOC 
oe ee) 
1!099C Overflow 
FLD1 DC Piz =)" = X’005D" 
FLD2 De P’2534' = X’02534C’ 
FLD3 DG PL3* 34” = X’O0034F"’ 
INSTRUCTION RESULT CONDITION CODE 
AP FLDL,FLDZ = X’529C’ S 
AP PiD>,f bz = X’02508C’ Z 
AP gl Oy Ae ed ry 8 = RK UZozZ IC” 2 
AP FLD1,FLD3 = X’029C’ Z 
AP FLD1L,=P'+93' = X’088C’ 2 
AP FLD1,=P'-95' = X’100D’ 1 
AP FLD1,=2Z2'3/7' SOC7 DATA EXCEPTION 
AP FLD1,=P'O' = X’005D’ 1 


TI 








eeEyT 





SP (Subtract Decimal) 





EXAMPLES: 
oe oy NUM1,NUM2 
NUM1 DC aa a0 Oy LOOC 
NUM2 DC Pius" 200" VOZU0C 
NUM1 ----> 100D (-100) 
SP NUM1+1 (1) , NUM2 
NUM1 DC Pr lLoo LOOC 
NUM2 DC Pio 00005C 
NUM1+1(1) ----> 5D Note: NUM1 now contains 
1O5D (-105) 
SP NUM1,=P'5' LOOC 
oie 
0O95C 
LA RZ, e2bbp1 Be sure to specify the 
LA Ro, lf LB LDZ Lengths here or you will get 
SP O25 RZ 702, RS) Unexpected results. 
SP NUM1,NUM1 LOG Zero a packed field 
= L0G But ZAP is better 
000C 
gd DC Ee 1) = XA OLOD’ 
FLD2 DC P’5498' = X'05498C’ 
FLD3 DC EY Giz o2 = we G25 5G" 
FLD4 DC Pius” =— © OO0OLSC’ 
INSTRUCTION RESULT CONDITION CODE 
SP gd Oe 8 He el By Bs = X*508D’ S 
SP PLD2Z, FisD1 = X"OS508C’ Z 
SP FiLDS;,FLD1 = A O24 2 
oe FLD4,FLD3 = X°6/238C’ 1 
SE FLD2, FLD3 = 2. OL 90D 1 
SP ee By BB ee oe 5B = X°'263D’ cS 
SP PDO g=e Oi 205" = KOOO0GC” O 
SP Pio p-E" 67252" = 325060” 5 
SP FPLD1,=P'-11' = X’O001C’ 2 
SP FLD1, FLD3+1 SOC7 DATA EXCEPTION 


fp: 











MP (Multiply Decimal) 


EXAMPLES: 
FLD3 = PL3'7/54' | FLD3 = PL3'754' 
FLD2 = P‘'7' | FLD2 = PL3'7' 
| 
MP FLD3, FLD2 FLD3= 05278C | MP FLD3,FLD2 -—-> S0OC6 
| SPECIFICATION 
FLD3 = PL3‘'7/54' | FLD3 = PL2'999' 
FLDI = P'-8'° | FLD2 = P!7' 
| 
MP FLD3, FLD1 FLD3= 06032D | MP FLD3, FLD2 --> SO0OC7 
| DATA EXCEPTION 
EFLD3S = Pls’ 990" | FLD3 = PLEO" 360" 
FLDI = P!7' | FLD2 = PL9'5' 
| 
MP FLD3,FLDL FLD3= 06993C MP FLD3,FLD2 --> S0OC6 
| SPECIFICATION 
FLD3 = P'360' 
FLD2 = PL3'5' 
MP FLD3,FLDL FLD3= 01800C 
MP FIBELDL, FIELDZ 
FIELDI DC PL4‘' 10° OO OU. D2. DE 
FIELD2 DC Pla 30” oS: UE 
00 00 50 OC OK 
MP FIELD] (2) ,=P'100' Specification, lengths equal 
MP FIELD1,=P‘'100' 
FIELDI1 be Pia oO. O00 U0 OC 
10 OC 
00 50 OC OK 
MP NUM, =PL2'500' 
NUM DC Piso? 500" OU: 5G: OC 
50 OC 


02!'50 OO OC Data Exception not 
enough leading zeroes 








OO LL EE Ee 


Examples: 


FiiDt 
FLD2 


nape ry 
FLD2Z 


DP 
DC 
DC 


Dr 


BS 


DC 
DC 





DP (Divide Decimal) 


FLD1L, FLD2 
Piso” L500" 
PLZ’ 200" 


Quotient, Ll 
5 


FisD1,FiaDZ 


Plat. 7 FGDZ 


Pi5s* £500" 
Ping “A. 


OL 20. UC 
Zu) OG 


—-L2 L2, Remainder 
=? OF: J 2 


specification, lengths are equal 
No room for the quotient 


J. 30. OC 
Ci 3c 


10!00!00 OC 
i 


Quotient > L1-L2, Decimal divide 
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EXAMPLES: 


DE 
DC 
DC 
DG 
DU 


AvUvAW PY 


CE 
OAs 
CP 
Cr 
Ge 
Cr 
oe 
OF 


CP (Compare Decimal) 


PY 2 
P* 549° 
Pr S000" 
le 20 ha 
X'OQ12A' 


a 


| OAIlaurw 


Cy 


POP PwUPoay 


Kt tO 
NO 


oA © 
345C 


OS000C 


UZoD 
O12A 


O12+ 
5000+ 


Lat 


345+ 


Lar 
Lo 
ERROR, 
ERROR, 


TS 


| VVVWVA 


345+ 

QO12+ 
PERS ra 
QO 
Q 
12+ 


& 
CG 
OG 
SG 
Se 
ie 


no sign in operand 
no sign in operand 


OF ONNNN FH 





Chapter 14 - External Routines & Linkage 


External Subroutines 


Until now we have been using internal subroutines; that is, subroutines which are actually part 
of the program that invokes them. It is much more useful to have subroutines which can be 
used by any program. These routines are called external subroutines because they can be 
created and maintained separately from the routines that invoke them. 


Two important factors make the use of external subroutines possible: 


L 


Subroutine source decks can be assembled separately and the object module can be 
stored into an object module library (a collection of object modules which reside on a 
storage device like a disk). 


The loader accepts as input not only an object module, but also an object module 
library. From these, the loader can construct an executable program that uses any 
required subroutines from the object module library. 


When we use subroutines that were written separately, there are certain things we need to 
know about that module: 


What parameters does it expect? 


Z. What does it return to you? 

oF Are any registers altered by the routine? (If any were altered, this would affect the way 
you write your routine, as you would have to avoid using the altered register) 

4. What register is used to return from the routine? (In other words, into which register 
do you want to put the return address) 

= How are the parameters passed’? 

NOTE: Use these notes (rather than the text) as your reference for this subject. 
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Standard Linkage Convention 


The standard linkage convention answers many of the problems mentioned above. In this 
convention, both the calling routine and the called routine have responsibilities. 


Responsibilities of the Calling Routine 
i? Establish an 18 word register save area, and put its address into register 13. 


2. Set up a parameter address list of input parameters to the routine to be called. The 
address of this list 1s put into register 1. 


oP Put into register 14 the address of the location in the calling program to which control 
is to be transferred on returning from the called routine. 


4. Obtain the address of the routine to be called, and put that address into register 15. 
5. Transfer control to the called routine by branching to the address in register 15. 
Responsibilities of the Called Routine 
l. On Entry 
a. Store the contents of R14,R15,R0,R1-R12 in the calling routine's save area. 
b. Establish addressability. 


‘of Establish an 18 word register save area of its own, and link it to the calling 
routine’ s save area by: 


i. Putting the address of the calling routine's save area in it's own save 
area. 
1. Store the address of its save area in the calling routine's register save 
area. 
d. Put the address of 1ts own save area into R13. 
Z. Perform Function —Obtain the input parameters from the calling program (R1 is 


pointing to these), perform its function, and store any results to be returned to the 
calling program. 


>. Return 


T7 





a. Obtain the address of the calling routine's save area from its own save area and 
put it into R13. 


b. Restore the contents of R14,R15,R0,R1-R12 from the calling routine's save 
area. 
C. Return control to the calling program by branching to the address in R14. 
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Save Area Format 


FULLWORD DISP CONTENTS 
NUMBER (base 10) 


BACKWARD POINTER (R13) 
FORWARD POINTER (R13) 





Backward pointer - points at the save area of the calling routine 


Forward pointer - points at the save area of the subroutine called 
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Register Conventions 


The OS Subroutine Linkage convention also includes some register conventions. These are: 


Register 0 - 


Register 1 - 


Register 13 - 


i 


Register 14 - 


Register 15 - 


On returning to the calling program, RO may contain the output from a 
subroutine whose entire output is a single numeric value (not common - 
usually done only in FORTRAN programs). 


On entry to the called program, R1 contains the address of a parameter 
address list. This list contains the address of the input parameters to be 
used by the called routine and/or the addresses of locations into which 
the called program is to store its output. 


R13 contains the address of the save area of the current routine. 


On entering the called routine R13 contains the address of the calling routine’ s 
Save area. 


The called routine puts the address of its own save area in R13 while it 
performs its function. 


On return from the called routine the address of the calling routine's save area is 
restored in R13. 


On entry to the called routine R14 contains the address of the instruction in the 
calling routine to which control will be transferred on return from the called 
routine. 


On entry to the called routine R15 contains the address of the entry point in the 
called program. Upon exit from a subroutine R15 may also be used to pass a 


return code back to the calling routine indicating the success or failure of the 


subroutine. 


Coding Conventions 


On entry, a called routine may satisfy its responsibilities by using the following sequence of 
code. It is normal practice to set up R12 as the base register. 


You should memorize the following sections of code, so that you need not spend a great deal 
of time thinking about them each time you use them. In addition you should understand them, 
since other installations may use slight variations on them, and since you will need to interpret 
(not just regurgitate) them on exams and quizzes. 
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Entry Linkage 


Upon entry to any routine (including the main routine) the following code should appear. 
Standard linkages are also described in your text in chapter 6. 


A 8 rtnname CSECT 

2 STM 14 422,742 (43) 

3 LR i2,;.2 

4 USING rtnname ,12 

2 LA 14,savearea * note 
6 ST 13,4(,14) 

a ST 14,8(,13) 

8 LR Loy oe 


NOTE: savearea will be defined in the storage area as 18 fullwords. 


L. 


Zz 


Each routine must have a unique name and a CSECT statement. 

The called routine must first store all registers in the save area reserved by the calling 
routine. Remember that the calling routine set up the save area and pointed R13 to it 
before invoking this routine. 

R15 will not be used as a base register since it has other usages. Instead, R12 will be 
used as the base register. This statement puts the address of the routine in R12. 


(remember that R15 already has the address of the routine) 


This statement will establish addressability for the routine, so that the labels can be 
converted to explicit addresses. 


Puts the address of the 18 fullword savearea into R14. Remember, we cannot put the 
Savearea address into R13 just yet, because we have not saved its' contents. 


This statement fills in the backward pointer. 
This statement fills in the forward pointer. 
The location of the current routine's save area is now put into R13, so that any other 


subroutines may be called (if necessary). Remember that when a routine is called, R13 
must contain the address of the calling routine's save area. 
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Exit Linkage Method | 


To exit a routine (return to the calling routine), the following code should be used: 


1 L 13,4(,13) 
2 LM 14, 12,22 (13) 
3 BR 14 
l. This regains the location of the calling routine's save area, restoring R13 to the value it 


had when the correct routine was entered. Remember that R13 points to the current 
routine’ s save area, and the second word of that save area points to the caller's save 
area. So that backward pointer (4 off of R13) can be accessed to restore R13. 


Zz This restores all of the other registers from the save area. It is the reverse of statement 
#2 in the entry code previously discussed. (If R15 is used to pass back a return code - 
indicating the success or failure of the routine - it should not be restored. In such a 
case, two statements will be required here, one to load R14 and one to load RO-R12). 


5. Finally R14, containing the location of the next instruction to execute upon return to 
the calling routine, is used to return to the calling routine. 


Exit Linkage Method 2 (Uncommon) 


For use when passing a return code (through register 15) and a value (through register 0). 


13,4(,13) 

A oe Gree 
1,12,24 (13) 
14 


mWDhY Fe 
BEES 


Exit Linkage Method 3 
For use when passing a return code (through register 15). 


13,4(,13) 
14,12(,13) 
0,12,20(13) 
14 


mWDY e 
BEES 
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Exit Linkage Method 4 (Uncommon) 


For use when passing a value (through register 0). 


L 13,4 (,43) 


if 
2 LM 14,1552 (43) 
3 LM Lpbeyee eS) 
4 BR 14 
NOTE: The Operating System (MVS) itself follows standard linkage conventions when 





it passes control to a user main program (which is viewed as an external 
subroutine as far as the operating system is concerned). 


Calling External Subroutines 


In order to call a subroutine, we need to know its address in our program. The problem is, 
when you code and assemble your program, you don't know where the subroutine is. 


We can't use type A address data (A-data) because these addresses must be resolved at 
assembly time and an external subroutine may be maintained separately and may reside in the 
object module library. 


Type V address data (V-data) solves this problem. The value generated at assembly time will 
appear to be a fullword of zero. Then the address of the subroutine will be filled in by the 
loader when the executable program is constructed in memory. Also, note that the use of V- 
data in a DC will not produce the address of the routine during assembly time, as shown 
below. 


000000 SUBADDR DC V (SUBRTN) 
caaniamaieaion 1S generated. But by execution time, this will 
have been filled in. 
L 15 ,=V (SUBRTN) 


BALR 14,15 
NOTE: these two lines of code fulfill our standard linkage requirements: 


R15 contains the address of the subroutine 
R14 contains the address to return to (in the calling routine). 
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Calling External Subroutines - Examples 


The following examples illustrate typical sequences of code which can be used to pass control 
to another routine. 


Sequence ii 


PARMLIST 


INPUT 
RESULT 


Sequence 2: 


SUBADR 


INPUT 
RESULT 


BALR 


DC 
DC 


DC 
DS 


BALR 


DG 


DC 
DS 


1 ,PARMLIST points Rl at parameter address 
list 

15,=V(SUBRTN) put address of entry point of 
subroutine in R15. 


14,15 Pass control to routine 

A (INPUT) parameter address list 

A (RESULT) 

amg 0 some input to subroutine 

F subroutine can put results here 


1 ,=A (INPUT, RESULT) 
Point Rl at parameter address list 


15,SUBADR Put address of entry point of 
subroutine in R15. 

a Wm Bs Pass control to routine 

V (SUBRTN) 

F'10' some input to subroutine 

F subroutine can put results here 


Now we can discuss how pass and retrieve from parameter lists!! 
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Parameter Lists and Passing Parameters 


Parameter Lists 


The information sent to the subroutines is referred to as parameters. You have been passing 
information to the subroutines in registers. For example when calling a routine for building a 
table you might put a table address in R2, input area address in R3, end of table (next 
available entry) in R4 etc. (here address of table, address of input area, and address of end of 
table storage area are the three parameters). 


When working with an external subroutine which is maintained separately you cannot assume 
that the subroutine is using R2 for a table address and R3 for an input address etc. Keeping 
these things in mind, a standard convention was developed. 


Under these conventions all the addresses sent to a subroutine are placed in a separate storage 
area, called a parameter list. (R1 is made to point at that storage.) When the control 1s 
transferred to the subroutine, it knows that all the necessary information is placed in a storage 
area where R1 is pointing. Thus, it can pick all the necessary information from the parameter 
list. 


You have to remember that when information is sent to a subroutine, the actual storage does 
not move. You are just informing the subroutine where the necessary things are located in the 
calling routine by providing addresses. 


Your parameter list must be fully documented in the ENTRY CONDITIONS of your 
subroutine. The parameter list must contain space for not only anything you pass to the 
subroutine, but ,also, for anything you need to return to the calling routine. 


For example a parameter list might look like: 


LA 1,PLIST 
L 15,=V (BUILD) 
BALR 14,15 


PLIST DC A (TABLE , INPUT, @NAV,RESULT) <-- PARAMETER LIST 
@NAV DC A (TABLE) Address of next available entry 
TABLE DS S90F 

RESULT DS EF 

INPUT DS CL80 
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LA 1,=A(TABLE, INPUT, @NAV, RESULT) 
Or 

LA 2, TABLE 

LA 3,INPUT 

LA 4,@NAV 

LA 5 ,RESULT 

STM 2,5,PLIST 

LA 1,PLIST 
PLIST DS 4F 


Now let's receive the parameters inside the called subroutine: 


BUILD CSECT 


Standard linkage <-- discussed in previous section 


LM 2,570 CL) Get all the parameters at the 


Now: R2 contains 
R3 contains 

R4 contains 

will put 

BRS. COntains 


+ + +F FF FF F F 


beginning of the program 


address of TABLE 

address of the INPUT area 

address of storage where BUILD 

the address of the next available entry 
the address of the result area 


Now the build routine 1s done, and you need to send back a value (let's say in R7) to the 
calling routme. Simply, store the value into the zero off of R5 (assuming that RS5 still has the 
address of the area where the result must be stored.) 


st t7O Cy) 


R5-> @ of RESULT area 


NOTE: Remember that you can have as many parameters in a parameter list as you 
want (depending on your needs). Furthermore, it is possible to use just one 
parameter list when information sent to many subroutines is the same. This is 
left to the programmer's judgement. 
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Examples of Internal and External Subroutines 


Problem: 


Note: 


A subroutine has to be called to add two numbers. The two numbers to be 
added are read, converted and stored in the MAIN routine at NUMI1 and 
NUM2. The result must be returned in storage named RESULT. 


The function of the subroutine 1s very simple but the thing to learn here is how 
to work with subroutines. 


First, let us write the program with an internal subroutine: 


MAIN 


CARD 
NUM1 
NUM2 
PLINE 


PRIRES 


* 


Gen7 HOAs 
USING 
XREAD 
ADECI 
XDECI 
BAL 
XDECO 
AERN TL 
BR 
LLORG 
DS 

DS 

DS 

DS 

DC 

DC 

DS 


TITLE 


MAIN, 15 
CARD, 80 
3, CARD 
4,0(,1) 
10, ADDEM 
4,PRTRES 
PLINE, 46 
14 


CL80O 

E 

Ef 

OCL46 

CoZt” &* 

Cine BeeUiat Lo’ 
CLii2 


"ADDEM ROUTINE' 


Establish Addressability 
Read a record 

Convert first number 
Convert second number 
Call ADDEM to add numbers 
Convert the result 

Print the result 

Return cConero. 


KKK KEKKKKEKE KEKE KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KEKE KEKE 


* 


= NOTE 


* 
* 


RESTORED AT THE END. 


THE RESULT IS SENT BACK IN R4 AND THUS IS NOT 


F .§ 
* 
* 
* 


KKEKKK KKK KKK KEKE KKK KEKE KKK KK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK IKKE KK 


* 


ADDEM 


ADDSAVE 


DS 
STM 
AR 
LM 
BR 
DS 
END 


OH 

5,4, ADDSAVE 
4,3 

5, 3,ADDSAVE 
1Q 

16oF 

MAIN 
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Now the same program, this time with an external subroutine: 


MAIN Contr 
OTM Dg Zp ee a) SAVE ALL REGS 
LR ae ie. GET BASE ADDRESS 
USING MAIN,12 EST ADDRESSABILITY 
LA 14,MAINSAV GET STORAGE ADDRESS 
nail 13,4(,14) SAVE BACKWARD POINTER 
oT LO p-) SAVE FORWARD POINTER 
LR Logue GET STORAGE @ IN R13 
XREAD CARD, 80 READ RECORD 
XDECI 3, CARD CONVERT FIRST NUMBER 
XDECI 4,0(,1) CONVERT SECOND NUMBER 
oT 3, NUMI1 STORE FIRST NUMBER 
no & 4,NUM2 STORE SECOND NUMBER 
LA Ly Plo POINT RL TO Plist 
L 15,=V (ADDEM) GET ROUTINE ADDRESS 
BALR 14,15 INVOKE SUBROUTINE 
L 3, RESULT PICK. KEoUda 
RDECO 3,7 PRIRES CONVERT RESULT 
XPRNT PLINE, 46 PRINT RESULT 
L L37e (7 13) GET BACKWARD POINTER 
LM Lo peg ke, Lo) RESTORE REGS 
BR 14 RETURN CONTROL 


TITLE ‘STORAGE FOR THE MAIN ROUTINE' 


LTORG 
CARD DS CL80 
NUM1 DS sy 
NUM2 DS y 
PLINE DS OCL46 
DG Ci i 1." 
DC C'THE RESULT IS'* 
PRIKES: Dos Cigke 
MAINSAV DS LOF REGISTER STORAGE 
RESULT DS sy TO BE FILLED BY SUBRTN 
ing ee owl DC A (NUM1,NUM2, RESULT) 
# 
END MAIN 


88 





Here is the external subroutine. Notice that it is a separate assembly (it has its own END 
Statement). 


TITLE 'ADDEM ROUTINE' 


* 


KAKEKKKEKKKE KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KEKE KK KEKE 


* * 
= NOTE: THE RESULT IS NOT SENT BACK IN R4, INSTEAD R4 = 
as POINTS AT THE STORAGE AREA WHERE THE RESULT SHOULD * 
x BE STORED! !! 


KRAKKKK KKK KK KKK KKK KEK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKEKEKK KEK 








* 


ADDEM 


NOW 


+ + FF FF FF F 


+ + + 


ADDSAVE 


Cone. 
oTM 
LR 
USING 
LA 

oT 

SL 

LR 

LM 


Le gcd gp ee lo) 
i sae las 

ADDEM, R12 
14, ADDSAVE 
13,4(,14) 
14,8(,13) 


(13,14 


Zy 8,0 11) 


SAVE ALL REGS 

GET BASE ADDRESS 

BEST ADDRESSABILITY 
GET STORAGE ADDRESS 
SAVE BACKWARD POINTER 
SAVE FORWARD POINTER 
GET STORAGE @ IN R13 
PICK PARAMETERS 


R2 HAS THE ADDRESS OF FIELD CONTAINING FIRST NUMBER 
R3 HAS THE ADDRESS OF FIELD CONTAINING SECOND NUMBER 
R4 HAS THE ADDRESS OF FIELD WHERE RESULT HAS TO BE 


STORED. 
if ae Om eae 
L yy) 
AR 2.2 
ST 340 (54) 
L Re es ee 
LM 14,127,12 (13) 
BR 14 
LTORG 
DS L8F 
END ADDEM 
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GET FIRST NUMBER 
GET SECOND NUMBER 
ADD THE NUMBERS 


STORE RESULT IN STORAGE 
SPECIFIED BY R4. REMEMBER 
RESULT IS ACTUALLY STORED 
IN THE MAIN PROGRAM. 


GET BACKWARD POINTER 
RESTORE REGS 
RETURN CONTROL 


STORAGE AREA FOR REGISTERS 


Chapter 15 - A USING Instruction Tutorial 


Introduction 


One of the most challenging concepts encountered by students of IBM Assembler Language is 
that of the USING assembler instruction, or directive. It doesn't generate any object code 
itself, but it directly influences how machine instructions are assembled. It is a promise by the 
programmer that certain register(s) will be available at execution time, and so determines 


which base registers and displacements are chosen by the assembler when converting implicit 
addresses. 


The most common application of USING is in program addressability. The following bit of 
code is fairly typical (although not necessarily recommended): 


1 MAIN COoOECT 

Z STMINST STM LA pega Lo) save regs; note explicit base (13) 
3 USING MAIN,15 R15 will have A(MAIN) at execution 
4 LAINST LA 14, SAVEAREA Get address of new Save area 

5 ST Loy (4.24) and save back pointer in new area 
6 ST 14,8; 13) and forward pointer in previous 

F LR oa eee set new save area pointer 

8 BALR 12,0 Get address of next inst into R12, 
a DROP 15 Say we no longer have need of R15, 
a 6 USING PART1,12 and tell assembler our new promise 
11 PART1 B SAVEAREA+18*4 Remainder of program follows 

eZ SAVEAREA DC Lor * =)" 


This bit of code has two USING instructions, one for location MAIN and one for location 
PARTI. The first USING, at statement 3, is a promise that, no matter where the program is 
loaded at execution time, register 15 can be expected to contain the address of the first 
instruction of the program. This information is used only during the assembly of the implicit 
address (of SAVEAREA) in the LA instruction at statement 4, in order to construct the object 
code of statement 4 with a valid base (R15) and displacement. 


The second USING, at statement 10, is a promise that R12 will have the address of PARTI at 
execution time. Note that this promise will be fulfilled when, at execution time, the BALR 
instruction at statement 8 is executed. 


Two definitions which will be very helpful in describing what follows are the domain and the 
range of a USING instruction. 


* The domain of a USING instruction begins where the USING instruction appears in a 
program, and it continues until the end of the program, except when: 
O A subsequent DROP instruction specifies the same base register 
O A subsequent USING instruction specifies the same register 
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* The range of a USING instruction is the 4096 bytes within a Control Section (CSECT) 
beginning at the base address specified in the USING 


In order for the assembler to convert implicit addresses to base/displacement, any instruction 
which refers to an implicit address must be situated within the domain of a USING whose 


range includes the referenced location. 


Here is the same bit of code with domains and ranges indicated: 


1 MAIN Comer <— | 
2 STMINST STM 14,420 12 113) | 
Domain of i—> 3 USING MAIN,15 | 
USING at | 4 LAINST LA 14, SAVEAREA | Range of USING at 
Stmt 3 > ST ig a gp ie | Statement 3 (up 
| 6 ST 1450, 43) | to 4096 bytes) 
| f, LR 13,14 | 
| 8 BALR 12,0 | 
|}-> 9 DROP 15 | 
Domain of|-> 10 USING PART1,12 | 
USING at | 11 PARTI B SAVEAREA+18*4 | <-| Range of USING 
Stmt 10 | Ls SAVEAREA DC > 18F'-1' | |} at Stmt 10 (up 
Vv 6 ai V V to 4096 bytes) 


In the example above, the range of the USING at statement 3 begins at location MAIN and 
ends at location MAIN+ 4095 (or earlier if the program is shorter than 4096 bytes). This 
means that location SAVEAREA referenced in statement 4 must be located between MAIN 
and MAIN+ 4095. The domain of that USING begins at statement 3 and ends at statement 9 
(the DROP instruction). This means that no instructions following statement 9 can be 
assembled with R15 as a base register. 


Similarly, the range of the USING at statement 10 is PART1 through PART1+ 4095S. Its 
domain begins at statement 10, so no instruction which preceeds statement 10 can be 
assembled with R12 asa base register. 


Note that the STM instruction at statement 2 is not within the domain of any USING, so it 
cannot have an implicit address for its second operand (which must be given explicitly, as it is 
in the example). Also, since statement 2 is not within the range of the second USING, label 
STMINST cannot be specified as an implicit address on any instruction following the DROP at 
statement 9 (assuming only these two USINGs, of course). 


It is clearly possible for USINGs to have overlapping ranges, as is the situation in the example 
after Statement 10. This is unimportant, though, because the USINGs do not have overlapping 
domains, and so the assembler has only one USING available for each instruction from which 
to select a base register. When it happens that there are USINGs with both overlapping 
domains and overlapping ranges, the assembler chooses for each implicit operand the base 
register which will result in the smallest displacement. This fact is important in what follows. 


9] 





As an aside, it is probably useful to notice that, in general, the instruction which will actually 
set the promised contents of a base register need not be proximate to the corresponding 
USING. In our example, the second USING almost directly follows the instruction which will 
set the register, while the instruction setting the register contents promised by the first USING 
is nowhere to be seen. 


A Closer Look 


Now, let's examine what the assembler does when its processes this program, particularly how 
it handles: 


4 LAINST LA 14, SAVEAREA Get address of new Save area 
and 
11 PARTI B SAVEAREA+18* 4 Remainder of program follows 


Since Statement 4 lies within the domain of the USING at Statement 3, and since 
SAVEAREA is within the range of that USING, R15 is an available base register. Since it is 
the only register available, the assembler chooses it. Since label SAVEAREA is 

4+ 4+ 4+ 4+ 2+ 2+ 4= 24= X'18' bytes into the USING range, the instruction is assembled 
as X'41E0F018' [student: verify this]. 


Similarly, since Statement 11 lies within the domain of the USING at Statement 10, and since 
SAVEAREA+ 18*4 is within the range of that USING, R12 is an available base register. 
Since it is the only base register available (R15 was DROPped), the assembler chooses it. 
Since SAVEAREA+ 18*4 is 4+ 18*4= 76= X'4C' bytes into the USING range, the 
instruction 1s assembled as X'47FOCO4C'. 


All of this should be verified by the student. Nothing unusual has been done, and verification 
should be straightforward. It should be clear that the reason Statement 3 is coded just so is the 
expectation that R15 really will have the memory address of the first byte of program code (the 
STM instruction) at the time of execution. In fact, let's see what would happen if we Jie to the 
assembler and tell it something which is incorrect! Let's change Statement 3 to pretend that 
R15 will have the address of LAINST (instead of MAIN) at execution time: 


5 USING LAINST,15 R15 will have A(LAINST) at execution 


Since label SAVEAREA is now 4+ 4+ 4+ 2+ 2+ 4= 20= X'14' bytes into the USING range, 
the instruction at Statement 3 is assembled as X'41E0F014'. Of course, we lied when we 
wrote the new Statement 3, but the assembler didn't know that and went ahead as though we 
were telling the truth. Now the object code for statement 4 actually loads the address of four 
bytes before SAVEAREA rather than SAVEAREA. 
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Our conclusion 1s that the assembler 1s very gullible! It believes whatever we tell it and then 
behaves accordingly. It doesn't know what we intend, only what we write. On the one hand, 
this means we must be careful in writing our USINGs so that the assembler generates the 
desired object code. On the other hand, this also means that we can trick the assembler into 
generating the object code we want, in circumstances where telling the truth simply isn't 
possible. The remainder of this note describes how to fool the assembler! (Well, not really, 
of course, but it helps to think of it that way.) 


How Can We Use Implicit Addresses Everywhere? 


Let's consider that program MAIN above begins a typical first semester exercise for the 
student of assembler. In this exercise, the student is to "process" two tables. Each table will 
have, say, up to 25 entries, and each entry will have, say, two fields: name (22 characters) and 
age (fullword binary), in that order. Before beginning the "process" (whatever that might be), 
each table entry must be initialized so that the name is blank and the age is zero. Thus, we will 
have a routine called INIT to which is passed each of the tables, in turn, for initialization: [to 
simplify the code, the address of the table, rather than a parameter list, is passed] 


LA ty TABI Get address of first table 


BAL 14,INIT and pass to INIT 
LA 1 iy TAB IE Z Do the same for the second table 


BAL 14, INIT 


When INIT receives control, it does the following: 


SR Cra Initial age value=0 
LA LO go Get counter for loop (Size of table) 
LR DAs pk Copy passed address of table 
* 
LOOP MVC 0(22,11),BLANKS *1* Set name to blanks 
ST 0,24(,11) *2* and age to zero 
LA Lepeo >; be) *3* Get to next entry 
* 
BCT 10, LOOP Continue until done 


BLANKS DC Cig =O Initial value for name 


For the purpose of this discussion, let's assume that the data BLANKS is located at X'63A' 
bytes into the range of the USING at statement 10 and that the Loop code lies within the 
domain of that USING. This means that the object code generated by the three statements 
marked *1*, *2*, and *3* 1s [student to verify this]: 


D2Z15BO00C63A 
SOQ0BO018 
41BOBO1C 
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We began with fairly standard source code, except that in the marked statements the explicit 
form of an operand is used, rather than the implicit form. Explicit operands were used 
because, at assembly time, there is no way to promise the address to be contained in R11 at 
execution time. In fact, R11 has a different address each time INIT is called! 


This is correct object code, but the explicit addresses create a number of problems: 


e There can be a lot of effort involved in calculating offsets and lengths 
* The calculations are prone to error 
“ Most of all, explicit addresses are inflexible; a change to one field may mean that all 


explicit addresses have to be recalculated 


How much nicer it would be to write: 


LOOP MVC NAME , BLANKS *1* Set name to blanks 


ST 0, AGE *2* and age to zero 
LA 11,NEXTENT *3* Get to next entry 


and get exactly the same object code as with explicit operands! Well, we can, and with all this 
background, it's actually pretty easy. 


The Solution: We Fool the Assembler 


Our goal, no matter how we accomplish it, is to generate the correct object code. In the case 
of the instruction at *1*, if we want to use NAME as the first operand, it must be at 
displacement 0 from base register 11, and it must have a length of 22. For the instruction at 
*2*, AGE must be on a fullword boundary at displacement 24 from base register 11. And for 
the instruction at *3*, NEXTENT must be at displacement 28 from base register 11. If we can 
do this, the same (correct) object code will be generated. 


The solution has two parts. First, we define fields labeled as we want, in the format we want. 
Let's place them just after BLANKS: 


DS OF Assure correct boundary alignments 
BLANKS DC Chzz* * Initial value for name 
NAME DS CiZZ Dummy NAME field for tables 
AGE DS EF Dummy AGE field for tables 


NEXTENT DS OH Dummy next entry ina table 


Now we trick the assembler. Since register 11 is the one we want as our base register, we tell 
the assembler that at execution time R11 will have the address of NAME. This is a lie, of 
course, because R11 will actually point to a table entry; but the assembler will believe us and 
will generate the correct object code. Here's what we do: adding one USING statement (and 
one DROP) to our original LOOP code, we place our marked instructions in a new USING 
domain (which overlaps the program USING domain established at Statement 10). 
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OR 


LA 
LR 


USING 
LOOP MVC 


noe k 
LA 


DROP 
Bor 


DS 


BLANKS DC 
NAME DS 
AGE DS 
NEXTENT DS 


ore. 
LOy 29 
eg 


NAME, 11 
NAME, BLANKS 
O, AGE 
l1,NEXTENT 
J. 


10, LOOP 


OF 
Chz2~ * 
CZ 2 

F 

OH 


x ]* 
xD* 


* 3x 


Initial age value=0 

Get counter for loop (size of table) 

Copy passed address of table to R11 
then lie to the assembler! 

Begin the domain of the lie 

set name to blanks 

and age to zero 

Get to next entry 

End the domain of the lie 


Continue until done 


Assure correct boundary alignments 
Initial value for name 

Dummy NAME field for tables 

Dummy AGE field for tables 

Dummy next entry ina table 


We must be careful, though; since the marked instructions lie within two overlapping USING 
domains and since they refer to operands which lie within two overlapping USING ranges 
(the new one begins at NAME and continues through NAME+ 4095), the assembler can 
choose between base registers 12 and 11 for each implicit address which lies within the 
overlapping ranges. 


For the instruction marked *1*, the first operand, NAME, is at offset X'650' in the range of 
the USING at Stmt 10 (remember that BLANKS is at X'63A' ), while it is at offset X'000' in 
the range of the USING just before LOOP. Therefore, following the rule mentioned at the end 
of the Introduction, the assembler chooses to use the base register which gives the smallest 
displacement, and the NAME operand is assembled with X'B000' as base/displacement (rather 
than X' C650" ). Since the definition of BLANKS lies outside the range of the new USING, the 
assembler can choose only R12 and assembles the BLANKS operand of *1* as X'C63A'. 

Since this is the desired object code, the lie has worked! The student should verify that *2* and 
*3* also assemble correctly. 


The student should also notice that at no time are the storage areas defined by NAME, AGE. 
and NEXTENT actually referenced! Base register R11 always has the address of a table entry 
and never has the address of NAME. This fact will shortly help us take the last step in solving 


our problem. 


If it weren't for the potential problem introduced by overlapping ranges, the solution would be 
nearly complete. Unfortunately, overlapping ranges make it easy for errors to be introduced. 
Consider what would happen if our storage areas were defined with BLANKS after, rather 
than before NAME: 


DS 


NAME DS 
AGE DS 


NEXTENT DS 
BLANKS DC 


OF 

CLiZZ 

FE 

OH 
Cige* * 


Assure correct boundary alignments 
Dummy NAME field for tables 

Dummy AGE field for tables 

Dummy next entry ina table 
Initial value for name 
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Now BLANKS lies within overlapping USING ranges and the assembler, following the 
smallest displacement rule, will choose to assemble the statement marked *1* as: 


D215BO0O0BO01C 


which is clearly incorrect object code [ student: explain why this happened]. It appears that our 
lie has gotten us into trouble and we need to find a way out. 


The Last Step: We Eliminate Overlapping USING Ranges 


Our best bet is to find a way to define the labels we want (NAME, AGE, and NEXTENT) so 
that they are outside any other possible USING range. That way, the assembler will choose 
R11 as the base register only when implicitly addressing those labels. Since a USING range is 
4096 bytes, we could make the program longer than 4096 bytes by inserting some large 
storage areas, then placing our fields after them, perhaps just before END. 


There is a better answer, though. It turns out that USING ranges are limited to addresses 
within a single control section, so our last step will be to define our labels in another control 
section. Here is one possibility: 


BLANKS Bes Giz Initial value for name 


ENTRY CSECT 

NAME; Do CihZZ Dummy NAME field for tables 
AGE DS F Dummy AGE field for tables 
NEXTENT DS OH Dummy next entry ina table 
x 


END MAIN 


and here is another: 


MAIN CSECT ; Beginning of program 

. bats 

ENTRY CSECT 

NAME DS Chie 2 Dummy NAME field for tables 

AGE DS F Dummy AGE field for tables 
NEXTENT DS OH Dummy next entry ina table 

* 

MAIN COoECT ; Resume original control section 
BLANKS DC CiZ2.” ~* Initial value for name 


In both cases, the labels NAME, AGE, and NEXTENT now lie outside the range of the 
USING at Statement 10 because they are located within a different control section. The 
assembler is forced to choose R12 as the base register for BLANKS in *1*, and will correctly 
choose R11 as the base register for NAME. That's it - we now generate the correct code in all 
circumstances because we eliminated overlapping USING ranges by isolating our labels in a 
different control section. 
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We can extend this solution to deal with situations where we want to use this trickery in 
multiple places within our program. Although we avoided parameter lists earlier for simplicity, 
they are the normal method to pass information to acalled routme. Thus we might call INIT 
with the following sequence: 


LA 1, =A (TABLE1 ) 


BAL 14, INIT 
LA 1,=A(TABLE2) 


BAL 14, INIT 


We now add an INITPRM CSECT (defining ATABLE) and rewrite INIT as: 


MAIN CSECI z Beginning of program 
INIT Ds OH 
SR G0 Initial age value=0O 
LA i228 Get counter for loop (size of table) 
USING ATABLE, 1 Trick assembler to gen correct code 
L 11, ATABLE Copy passed address of table to Rll 
DROP 1 then end USING domain for Rl 
* 
USING NAME, 11 Begin the domain of the lie 
LOOP MVC NAME, BLANKS *1* Set name to blanks 
oe O, AGE *2* and age to zero 
LA 11,NEXTENT *3* Get to next entry 
DROP 11 End the domain of the lie 
* 
BCT 10, LOOP Continue until done 
* 
ENTRY CSOECT 
NAME DS Ch22 Dummy NAME field for tables 
AGE DS EF Dummy AGE field for tables 
NEXTENT DS OH Dummy next entry ina table 
* 
INITPRM CSECT 
ATABLE DS A Address of passed table 
* 
MAIN CSECT , Resume original control section 
BLANKS DC Clizea° 7 Initial value for name 


Now we are done! We've found a way to fool the assembler into generating the object code we 
need in circumstances where it isn't possible to get the result "truthfully." By eliminating 
overlapping USING ranges, we' ve also assured that incorrect base registers are less likely to 
be chosen. By isolating each group of storage areas associated with a "trick" in a separate 
control section, we have reduced potential errors which might arise from overlapping USING 
ranges in a "multiple trick" situation. There is only one minor, helpful but unnecessary change 
left which we can make if we wish. 
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The Final Last Step: We Stop Wasting Space 


We mentioned earlier that none of the storage areas created for the purpose of tricking the 
assembler is ever actually referenced or changed. This is the result of our trick, and it leaves 
these storage areas doing nothing but wasting space. All they are needed for is to make it 
possible for the assembler to see the offsets and lengths of the various labels. 


Since the storage isn't needed, just the labels, we can change the control sections to be dummy 
control sections. Dummy control sections reserve no Storage; they are simply sets of labels for 
the assembler to refer to in situations such as we have created here for our trick. The savings 
in storage is minimal in our example, but in "real" programs the reduction can be noticeable. 


Dummy control sections are implemented by using the DSECT instruction in place of CSECT. 
This would mean that our labels would be defined as follows: 


* 


ENTRY DSBCT 

NAME DS Cine 2 Dummy NAME field for tables 

AGE DS F Dummy AGE field for tables 
NEXTENT DS OH Dummy next entry ina table 

* 

INITPRM DSECT 

ATABLE DS A Address of passed table 

* 

MAIN CSoECT =; Resume original control section 


BLANKS De Chze " Initial value for name 


Thus, while MAIN is a CSECT, ENTRY and INITPRM are DSECTs which take up no 
storage. 


Conclusion 


Assembler programming can be greatly simplified by means of the USING instruction. With 
the sleight-of-hand described in this note, the assembler can be convinced to generate correct 
object code from implicit addresses in situations where implicit addresses might not seem 
possible. By isolating labels used in the trickery into CSECTs or DSECTs, potential addressing 
errors are reduced. By use of DSECTs, wasted memory is reduced. 


MS, March 1998 
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Chapter 16 - Addressability and USING | 


This section will demonstrate the use of the USING and DROP assembler directives. The 
first thing to note is that the USING and DROP statements do NOT generate any object code, 
and therefore ARE NOT EXECUTED BY THE CPU when your program 1s actually "run" by 


the CPU! 


The purpose of the USING and DROP directives is to make things easier for the programmer. 
They are used by the programmer to inform the assembler (that is the actual program that 1s 
used to assemble your assembly language program) how to go about calculating the 
displacements from your "base" to the desired address of reference. 


The method of explanation that we will use for this is that of examples. 


O0010F8 
OO10F8 
0010F8 
OO10FC 
001100 
001102 
001106 
OO110A 
00110E 
001112 
001114 
001116 
OO111A 
00111E 
00111E 


001120 
001124 
001128 
00112C 
001130 
001134 


5830 
5030 
1B44 
4770 
5840 
5850 
5860 
1A45 
1A46 
5040 
A7F0O 


O7FE 


PP OTTTP VP 


00000000 
00000000 
00000037 
OOO000FF 
00001000 
FFFFFFFF 


MY PGM 


START 


LOOP 


LP5 


TEST 


SAVEAREA 


NUM3 
ANSWER 


CSECT 


USING START,15 


3,TEST 
3, SAVEAREA 
4,4 
B'0111',LP5 
4,NUM 

5 ,NUM2 

6 ,NUM3 
4,5 

4,6 

4, ANSWER 
LOOP 

OH 

14 

15 

F'O' 
F'Q' 
F'55' 
F'255' 
F'4096' 
F'-1' 

MY PGM 


In the above CSECT, the displacement portions of the D(X,B) addresses have not been 
included but would appear in the underlined portions of the object code (you should be able to 
calculate what they would be.) Note that it would not matter what value the location counter 
had in it at the beginning of this CSECT... the displacement values would be the same as 
long as the program segment was the same. 


De 





Let's see what happens if we change the label in the USING directive a little bit: 


0010F8 MY PGM CSECT 
0010F8 USING LOOP, 15 
0010F8 5830 F__ START L 3, TEST 
0010FC 5030 F_ ST 3, SAVEAREA 
001100 1B44 SR 4,4 
001102 4770 F___ LOOP BC B'0111',LP5 
001106 5840 F L 4,NUM 
00110A 5850 F___ L 5 ,NUM2 
00110E 5860 F_ L 6 ,NUM3 
001112 1A45 AR 4,5 
001114 1A46 AR 4,6 
001116 5040 F__ ST 4,ANSWER 
00111A 47FO F B LOOP 
00111E LP5 DS OH 
00111E 07FE BR 14 

DROP 15 
001120 00000000 TEST DC F'0' 
001124 00000000 SAVEAREA DC F'0' 
001128 00000037 NUM DC F'55' 
00112C 000000FF NUM2 DC F'255' 
001130 00001000 NUM3 DC F'4096' 
001134 FFFFFFFF ANSWER DC F'-1' 

END MYPGM 


In the program given above there might not be any addressability error but the program will 
not run correctly because of the improper statement "USING LOOP,15".. The reason it is 
improper is that the base register does not contain the base address (address of the LOOP), 
register 15 contains the base address of the beginning of the CSECT. Notice that the 
instruction at LOC 00110A would really attempt to load register 5 with the fullword stored at 
the address 34 bytes past the value in register 15 (that is X'2A'(,15)) which would be 
X'OQO1LOF8' + X'00002A" which is X'001122'... obviously NOT the address we would 
have wanted to be used!!! X'001122'is not even on a fullword boundary!! All this happened 
because the USING directive had the wrong label reference on it. This caused the assembler 
to view that instruction at address X'00110A" to be assembled as: 


L 9, NUM2-LOOP (,15) 
instead of: L 5, NUM2~START (,15) 
as 1t should have been since register 15 would contain the EPA... not the address of where the 
label LOOP would be. 
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As a final example, observe the following program segments and its interpretation by the 
assembler: 


ORIGINAL SOURCE CODE 


SOURCE CODE AS VIEWED BY ASSEMBLER 





1 MYPGM CSECT MY PGM CSECT 
2 12 3,TEST F 3, 
3 USING MYPGM,15 
4 ST 3, SAVEAREA ST 3,SAVEAREA-MYPGM(,15) 
5 SR 4,4 SR 4,4 
6 LOOP BNZ LP5 LOOP BNZ LP5-MYPGM(,15) 
7 DROP 
8 USING NUM, 2 
9 if 4,NUM L 4 ,NUM-NUM (, 2) 
10 r 5 ,NUM2 : 5 ,NUM2-NUM (, 2) 
11 ie 6 ,NUM3 L 6 ,NUM3-NUM (, 2) 
Ve AR 4,5 AR 4,5 
13 AR 4,6 AR 4,6 
14 ST 4, ANSWER ST 4 ,ANSWER-NUM (, 2) 
15 B LOOP B 
16 LpPS5 DS OH LP5 DS OH 
17 BR 14 BR 14 
18 TEST DC F'Q' TEST DC F'Q' 
19 SAVEAREA DC F'0Q' SAVEAREA DC F'Q' 
20 NUM DC F'Q' NUM DC F'Q' 
21 NUM2 DC F'0' NUM2 DC F'Q' 
22 NUM3 DC F'O' NUM3 DC F'Q' 
23 ANSWER DC F'0' ANSWER DC F'Q' 
END MYPGM END MYPGM 


Note that the load instruction in line 2 and the branch in line 15 cannot be assembled! This is 
because the instruction being assembled is not within the domain of any USING. In line 2 
there are no active base registers at all and in line 15 the label loop is outside the range of 
register 2 (the only active base register). 
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Chapter 17 - DSECTs 


Syntax: label DSECT 


General Discussion 


Just like a CSECT, a dummy section or DSECT defines the format of an area in storage. 
Unlike a CSECT, it generates no object code. (No storage is defmed.) The end of a DSECT 
is delimited by another DSECT, CSECT or END statement. A DSECT has no value except as 
the base address of a USING instruction. Of course, a CSECT or any other label can be a 
USING base, but a DSECT will save some storage. (See the USING Tutorial elsewhere in 
this book. ) 


Suppose TABLE consists of 40 entries and each entry contains student name and student social 
security number. 


TABLE DS 40CL29 


Now let us assume that R3 points at the beginning of the table. In order to refer to the name, 
we would use something like 0 (, 3) and to refer to dept, 20 (, 3). It would be preferable to 
refer to each field by a name (implicit address) rather than by a base and displacement 
(explicit address); it would make the program easier to understand. 


The USING instruction makes it possible to refer to each field by a meaningful name. 


Note: It is good beginning practice to start DSECT labels with a few common characters. It 
is not a requirement but it helps in identifying a DSECT label from a regular label. 


So for the above table the DSECT could be defined as 


OO0O0000 TABLNTRY DSECT , The name of the DSECT 
OOO0000 TABLNAME DS CL20 The location counter always 
000014 TABLSSN DS CL9 starts at O for each DSECT 
O0O001D ‘TABLNEXT EQU * Start of next entry 


The DSECT defines the format of one table entry. Again, it does not reserve any storage. 
In our program, we still have to define the table itself: 


TABLE DS 20CL29 


To make use of the DSECT: 
LA 3, TABLE GET ADDR OF TABLE AS USUAL 
USING TABLNTRY , 3 
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The USING statement connects the register and the set of labels in the DSECT. It tells the 
computer that R3 contains the address of an area whose contents are described by the DSECT. 
In other words, it tells the computer to place the labels, defined by the specified DSECT, at 
the address contained in R3. It will not change the contents of R3, it is programmer's 
responsibility to make sure that register contains proper address. After the USING statement, 
the DSECT labels can be freely used instead of using explicit addresses. 


MVC TABLNAME , CARDNAME 

MVC TABLSSN , CARDSSN 
instead of 

MVC 0(20,3) , CARDNAME 

MVC 20(9,3) ,CARDSSN 


When we are done processing the current entry, simply set R3 to the address of the next one: 
LA 3, TABLNEXT 

Now the labels in the DSECT refer to the second entry in the table. 

Be careful where R3 points. Make sure it always points into the table. Strange results can 

occur if the expected value is not in the register. Also, be sure you initialize the register 

before you use It. 

When you are finished with the DSECT, DROP the registers. 


DROP R,, R, ...-R,. 


If you neglect to DROP the registers, you may get very unusual problems later in your 
program. 


For example, if you have 


MAIN Bron th Gah 


BUILD Conc Lr 
USING TABLNTRY, 9 


REPORT CSECT 
USING TABLNTRY, 4 
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You want the labels in BUILD to be assembled with R9 and the labels in REPORT with R4-. 
If you don't DROP R9 after BUILD, this won't happen. In CSCI 464, you will learn all the 
rules that are used to decide which base register to use, if there are two possible regs. Suffice 
to say for now, the assembler picks the higher number register, which is R9. If R9 had been 
dropped, this wouldn't be the case. 


In REPORT, when your program is run, R4 contains the address of the table. Who knows 
what R9 contains. Addresses are resolved using the contents of R9. What exactly happens is 
dependent on the contents of R9. 


Advantages 


1) Readability of your program is improved 
2) Easier to alter your program 


If there is a change in the format of your storage, simply change the DSECT. There's no need 
to change a bunch of displacements. 


LA 3, TABLE 
LA 4, INPUT 
USING TABLNTRY, 3 
USING INPUT, 4 
XAREAD INPUT, 80 
DOL BM ENDDOL 
MVC TABLNAME , CARDNAME 
MVC TLTABLSSN, CARDSSN 


LA 3, TABLNEXT 
XREAD INPUT, 80 
B DOL 

ENDDOI1 DS OH 


Encoding DSECT Labels 


MVC TABLSSN,CARDSSN -> D2 08 3 014 4 014 


! l=—=> Displacement in 

Donic. 

| ee > Base specified 
by you 


LA 5, TABLSSN -> 41 50 3014 
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Chapter 18 - TRT and EXecute Examples 


Note: 


EKxample 1: 


Solution: 


When using TRT, NEVER use R1 and R2 for anything other than very 
temporary values, because execution of the TRT instruction alters the value of 
these registers implicitly. Be careful!! 


Assume that the input data has a name field arranged in the order of "Last, 
First". You have already read the data and now you want to rearrange the name 
as "First Last". The maximum length of the name field is 20 bytes. 


Let us first figure out the logic to do this: 


Locate the ',' which will indicate ending of the last name. Calculate length of 
the last name. Locate the ending of the first name (ends with a blank). 
Calculate the length of the first name. Once you have these values, you can now 
rearrange the name. 


The code for this example is given on the next page. An instruction by 
instruction explanation of the each line of code follows the code listing. 


The code has lot of dotted lines which indicate that there is some other code 
here which does not pertain to this example. 


In the code we will assume that the name has already been read and placed in a 
field named NAME. The code will rearrange the name and place the result in 
NAMEOUT. 


REARRANG CoBCTr (CODE FOR EXAMPLE 1) 


+ 


FOLLOWING IS THE CODE FOR THE REARRANGING PROCESS 


MV I NAMEOUT,C* ' CLEAR THE OUTPUT 
MVC NAMEOUT+1 (19) , NAMEOUT FIELD 

LA 3, NAME BEG. OF LAST NAME 

URS NAME, SCANTBL LOOK FOR COMMA 

LR ou | NOTE WHERE LAST NAME ENDS 
ey at pS CALC. LENGTH OF LAST NAME 
LA 4,2(,1) BEG. OF FIRST NAME 
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TRT 


aR 


BOR 


BX 


LA 


BCIK 


BX 


0(20,4),SCANTBL 


1,4 


L7 


tL, 2 RorIMOVE 


6, NAMEOUT+2 (1) 


oy 0 


9, LASTMOVE 


LOOK FOR BLANK 
(END OF FIRST NAME) 


LENGTH OF FIRST NAME 


ENCODED LENGTH IS 
LESS THAN ACTUAL 


MOVE IN FIRST NAME 
GET THE ADDRESS 
WHERE LAST NAME 
SHOULD BE PLACED. 


ENCODED LENGTH IS 
LESS THAN ACTUAL. 


MOVE IN LAST NAME 


= AT THIS POINT NAMEOUT HAS THE REARRANGED NAME 


SCANTBL 


NAME: 
MARKER 
NAMEOUT 


FRSTMOVE 
LAS TMOVE 


ORG 


DC 
DS 
MVC 
MVC 


DROP 
END 


14 


256%" 00" 
SCANTBI+tC* ,” 
X' FE’ 
SCANTBL+C! ! 
xX EE 

CLiZ0 

‘ex ' 

CL20 


NAMEOUT (0) , 0 (4) 
O(0,6),NAMEIN 


REARRANG 


MOVE IN FIRST NAME 
MOVE IN LAST NAME 


Instruction by instruction explanation of the above program: 


MVI and MVC 


LA 


Used to clear out the NAMEOUT field. 


To save the address of the beginning of the last name, used for length 
calculation. 


107 





TRT 
LR and SR 


LA 


TRI 


SR 
BCTR 
EX 


LA 


BCTR 


EX 


SCAN TBL 


Find the location of the comma within the input field (NAME). 
Calculate length of last name and save it in RS. 


Point to beginning of first name. R1 is pointing at the comma, there is a 
blank after that so we add 2 to R1 to get the beginning point of first 
name in R4. 


Using R4 as the starting point, scan the first to find the end of it. The 
end will be denoted by a blank. We have used length as 20 even though 
there might not be 20 more bytes to scan. This might cause a problem if 
the name occupies all the 20 bytes. To take care of this problem, we 
have included a marker field containing a blank. This will ensure that 
the scan does not go on beyond the name field. The proper way of doing 
it would be to calculate the remaining length and EXecute the TRT 
instruction. 


Calculate length of first name & save it in RI. 
Subtract 1 since encoded length is one less than the actual length. 


Move first name, and only the first name, into the target field 
(NAMEOUT). Since R4 points at the beginning of first name, it is used 
as the source field address in the MVC statement. 


Get the address of the location where last name should be placed in the 
target field. A displacement of 2 1s coded to allow for a blank between 
the names and because R1 was BCTR'd earlier. 


Subtract 1 since encoded length is one less than the actual length. 


Move the last name into the target field (NAMEOUT) after the first 
name and after the blank that separates the two names. The address of 
the target area (where last name should go) was already placed in R6. 
So, R6 is used as the address of the target area in the MVC statement. 


The table is designed to stop the TRT scan once it finds a',' or a blank. 


That 1s why the whole table is filled with X'00' except at the location of 
',' and blank where we have X'FF'. 
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Example 2: 





In this example we will read a record containing a variable length numeric field. 


convert it to binary, and place it in a fullword (NUMBER). The field in the 
input record can start in any column and can be of length ranging from 1 to 5 


digits. 


The code for this example follows. This is a complete code and you can try 
executing it with your own test data. 


PICKNUM 


* 


LOOP 


SCANDIG 


* 


SCANBLNK 


PEG 
MARKER 


Come. 


XREAD 
BM 


TRT 
LR 
dai 
SR 
BCR 
Bi X 
CVE 
oT 


XDUMP 


XREAD 


DS 


Bix 


LTORG 
DC 
ORG 
DC 
ORG 


De 
ORG 
De 
ORG 


DS 
DC 


INPUT, 80 
BOF 


INPUT, SCANDIG 
Sym 

0 (80,3) ,SCANBLNK 
dog 

in 

1, PACKIT 

3, TEMP 

3,NUMBER 


NUMBER, 4 


iB 0 Migee one 
LOOP 


OH 
14 
250%" 00" 


SCANDIG+X'FO' 
LOX'FF' 


ZI6K" 00" 
SCANBLNK+C! ! 
a ee 


CLe0 
C v | 
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READ THE 
DO WHILE 


LOOK FOR 


SAVE THE 


LOOK FOR 


CALC. 


RECORD 
NOT EOF 


PiRot DIGIT 
BEG. @ 


BLANK 


THE LENGTH 


OF THE FIELD 
ENCODED LENGTH 


PACK THE 


PLE GD 


CONVERT TO BINARY 
SAVE IT IN STORAGE 
CHECK NUMBER 


READ NEXT RECORD 


EINDDO 














NUMBER 
TEMP 


* 


PACKIT 


* 


DS i 

Ds D 

PACK TEMP,0O(0O, 2) CONVERT NUMBER TO PACK 
DROP 


END PICKNUM 


Instruction by instruction explanation of the above program: 


XREAD and BM 


TRI 


LR 


TRI 


SR 


BCTR 


jap, 4 


CVB and ST 


XDUMP 


XREAD/B 


SCANDIG 


SCANBLNK 


Read the record and check for end of file. 

Locate the first digit. 

Save beginning point of the field. 

Locate end of the field. The end 1s indicated by a blank. The scanning 
Starts at the 0(R3) because that is where the first digit was found. 
Similar to the TRT in the first example, the proper way to do this 
scanning will be to calculate the remaining length of INPUT and then 
Exexute the TRT instruction. Once again we have placed a blank 
marker at the end of INPUT to force the scan to stop in the worst case. 
Calculate the length of the field and save it in R1. 

Subtract 1 since encoded length is one less than the actual length. 

Pack the field in to a 8 byte temporary field. Since R3 points at the 
beginning of the field, it is used as the source field address in the PACK 


statement. 


Convert the packed number to binary and store it 1n the specified 
storage. 


Check and make sure that the result 1s correct. 
Read next record and branch to check EOF. 


This table is designed to stop the TRI scan only when a valid digit is 
encountered. 


This table is designed to stop the TRT scan only when a blank is 
encountered. 
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Chapter 19 - Macro Instructions & 
Conditional Assembly 


The IBM Macro Language 


Extension of basic assembler language. 


Means of generating (at assembly time) a commonly used set of instructions as many 
times as needed. 


The necessary statements are included in the macro. So when the macro is called 
(coded), it will produce the necessary statement / statements. It can be called any 
number of times for generating the code. For example, a macro for generating standard 
linkage can be written and later it can be called in all the routines, thus saving a lot of 


typing. 
Code only the macro name when the statements are to be generated. 


Also it must be clear that macros do NOT save any space, they just save typing and 
thus typing errors. 


Macros are processed prior to assembly, so a macro loop is different than a loop in 
assembler code. 


A macro is a separate entities from the programmers code. All macros should be coded 
in the beginning before the first CSECT. 


When the macro is invoked, the instructions are generated as if you had typed them in 
the routine itself. 


All the macro generated code has a'+' in the first column. 
Advantages: 


- Simplify the coding of programs 
- Reduce number of coding errors 
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The Difference Between Macros and Subroutines 


Subroutines: 
~ Branch out of main logic into a separate logic. 
~ Performed identically each time it 1s executed. 
- Subroutines are invoked during execution time. 
Macros: 


- Generates assembler code instructions where it 1s coded. 

- Depending on how it is coded, different or identical instructions may be 
generated. 

— Macros are invoked during assembly time. 


Macro Definition 


All code in a macro lies between MACRO and MEND statements. 


MACRO 

MACNAME, <---—- Prototype statement (macro name and 
parameter declarations) 1s used to 
invoke the macro. 

MEND 


Macros can be defined within a program (called a source macro definition) or may be defined 
in a library of macros (where it is a library macro definition). Macros usually start off as 
source macros in a single program. They may be later placed in a macro library so that other 
assembler programs may have access to them. EQUREGS is an example of this. 


In ASSIST, all source macro definitions must appear before the first CSECT/DSECT. You 
may not use EJECT, TITLE, SPACE statements in a macro to space the macro code because 
the macro code is processed pre-assembly. So if you have any of these statements m a macro 
then the affect of these statements will be seen when the macro is invoked and not within the 
macro itself. Remember the macro statements are processed before the program is assembled. 
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Format of a Macro Definition 
MACRO - The header statement must be first statement 
anyname - Prototype statement 


- Body of the Macro 
contains Assembler code and also macro processing statements. 


MEND - Trailer statement (provides exit) 
- It must be the last statement 
- It may have a sequence symbol in column 1 
- You cannot have more than one MEND statement within a macro 


Prototype Statement 


= The name field is required for defining and invoking a macro. 
* It must be right after the header statement (MACRO). 
Format: 
label or symbol O-many parameters 
blank 


| 1f used must have variable symbol e.g. 


Parameters can be positional or keyword parameters 


MACRO <-- Header statement 
& LABEL EXMPL1 &éA,&B, &C <-- Name field 


This 1s what could be typed inside the program. 
CATIA EXMPL1 VAL1 , VAL2 , VAL3 
By this mvoking statement, 
2 &A will be replaced by VALI 
* &B will be replaced by VAL2 
* &C will be replaced by VAL3 


throughout the macro expansion. 
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& LABEL, 














In the above example position of the parameter is important. When the macro is invoked the 
first value coded is assigned to the first parameter, second value to second parameter and so on 
so forth. So you must be very careful while coding the values, a mismatch will give you 
unexpected results. Otherwise, use KEYWORD parameters. If a combination of positional 
and keyword parameters are used, all the positional parameters must be coded before coding 
the keyword parameters. 


For example, if the prototype statement is coded as follows: 
&LABEL EXMPL2 &D,&E, &A=, &B=, &C=20 
and it is invoked by a routine as follows: 
CALL2 EXMPL2 VAL3 , VAL4 , BD=VAL1 , A=(R5,R7) ,C=, 


D will get VAL3, E will get VAL4, B will get VALI, A will get (R5,R7) and C will get null 
value. 


In this example position of A, B, and C is not important because parameter name is also coded 
along with the value. D is the first positional parameter and E is the second positional 
parameter. So when the values are assigned D will get VAL3 and E will get VAL4. 


NOTE: The rules are a little different if you are using a combination of keyword and 
positional parameters in a prototype statement than when you are using actual 
High Level Assembler (not ASSIST). Talk to your instructor if you want to 
know the differences. 


If there is nothing after the '=', that means a null value is assigned to that parameter. F or 
positional parameters, a null value is assigned to a parameter by coding nothing for the 
parameter value in the calling statement. 


Continuation: When a macro is invoked during assembly, if the prototype statement 
exceeds one line then break it at a comma, put some character (usually a 
'x') in column 72 and start on next line in column 16. 


Body of Macro: Body of macro consists of the following: 

- Assembler instructions which are generated when the macro is 
expanded. 

- Conditional assembly instructions used for generating different 
code depending on different requirements. These statements are 
not generated when macro is expanded. 

- Macro inner instructions 

— macro processing instructions, not generated with macro 
expansion. 
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~ MNOTE instruction for generating error/warning messages 
- MEXIT instruction for terminating the macro processing in 
middle. 


_ Comments 


.* - not generated when macro expands 
* - generated with macro expansion 


Variable Symbols 


Definition 


Variable symbols are symbols that can be assigned different values by either the programmer 
or the assembler. 


Naming convention : 
&< Alphabetic> < up to 6 letters/ digits 


There are three types of variable symbol: 
I. Symbolic parameters (Assigned values by programmer invoking a macro) 


II. System variable symbols (Assigned values by assembler) 


The following are the most commonly used system variable symbols: 


&SYSNDX &SYSDATE &SYSTIME 
&5YSoLIsSt &5SYSPARM &SYSECT 


Note: Do not start your variable names with &SYS. 


ITI. Set symbols (Assigned values by programmer in conditional assembly instruction) 
A. Arithmetic set symbols: SETA 
B. Binary set symbols: SETB 
C Character set symbols: SETC 
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+. 


Symbolic Parameters 


Values assigned by the programmer. 


Keyword & positional. 


When macros are expanded, the SYMBOLIC PARAMETERS are replaced by the 
values that are assigned to them when the macro is invoked. Look at the following 
macro and the generated code: 


KRKRERERRKRKEKRKRRKRKRK RK KKRKRKKKK RK KKK KERR KRKKE KKK KR KK KKK KEKE SK 


This macro demonstrates how the symbolic parameters 
are replaced by the assigned values. 


compute the sum of two binary integers stored at the 
specified addresses. 


* * 
* * 
* * 
* * 
* In effect this macro generates the necessary code to * 
* * 
* * 
* * 
* , 


KKKKKKKKKE KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KH 


MACRO 
& LABEL ADD 
& LABEL L 
A 
ew 
MEND 


MAIN Concer 


SUMIT ADD 
SUMIT L 


no 


ADD 


oT 


END 


&NUM1, &NUM2 


5, &NUM1 
5, &NUM2 
5S, &NUM1 


FLD1L, FLD2 
Oy ba 
a7 FiDZ 
ome ate Del 


FPLD3, FLD4 
yp iS 
5, FLD4 
op aS 


MAIN 
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<<== Invoke the macro 
<< Code generated 

<< by the 

<< macro 


<<== Invoke the macro 
<< Code generated 

<< by the 

<< macro 





System Variable Symbols 


Values assigned by assembler 
Some of the system variable symbols are 


&ESYSNDX, &SYSLIST, &SYSDATE, 
&ESYSTIME, &SYSPARM, &SYSECT 
&SYSNDX 
Concatenates a 4 digit number to a symbol of 4 or fewer characters. 
It is used to generate a unique suffix for a symbol each time a macro is called. 


It assigns a value of OOO! the first time a macro is invoked, which is incremented by 
one for each subsequent invocation of that macro. 


KKK KKKRKEKEKRKKEKKKKKEKK KKK KKK K KK KKK KK KK KKK KKK KK KKK KH KKEKKIKAaEKKIKIKEKEHK 


The following three MACRO examples relate to the use of 
&SYSNDX 


+ + + F 


First Example : shows the problem caused by a macro which 
generates labels - thus the need of &SYSNDX* 
by the first example 


Third Example : Same as second example but shows a more 


rag 

* 

* 

* 

* 

* 

* 

* second Example: uses &SYSNDX to resolve the problem caused 
* 

* 

* 

* sophisticated way of using &SYSNDX 
~ 

* 


* 
* 
* 
* 
* 
* 
* 
* 


ye ite. Ge. ds, ie, i. ae, Te aa, a. Ge ee, a, Se ee aE, Ge, Ver Se, es ee ee, ee ae Se Se a Se Ee. Se a ae a re Se alr a, Sle, Be, r,s Se» Se. Se, ee, ae, 


KEKKKKKKKKR KKK KKK KKK KKK KKE KKK KKK KKKKKKKKKKKKKKKEKKKKAKKKEKEKK KEK 


* * 
* First Example : shows the problem caused by a macro which * 
* generates labels - thus the need of &SYSNDX* 
* * 


KKK KKK KKK KKK KKK KKK KKK KKK KEKKEKKKE KKK KKK KKK KKKKEKKKKKHKKKKKAAKIKK KKK 
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MACRO 
& LABEL ADD &NUM1, &NUM2 
& LABEL oa 5, OAVE 
L 5, &NUM1L 
A 5, &NUM2 
aL 5, &NUM1L 
B NEXT 
SAVE DC eae Mk 
NEXT Ds OH 
L 5, SAVE 
MEND 
MAIN CSBcT 
ADD FLD1, FLD2 
+ oa DpoORVE 
+ L Spb ODL 
+ A 5, FLD2 
+ oe Oy ak 
+ B NEXT 
+SAVE DG | tie Ok 
+NEXT DS OH 
+ L Dd; CAVE 
ADD FLD1, FLD2 
+ oye hs 5, SAVE 
+ L Dy EF De 
+ A oe so 
+ OL oye uD 
+ B NEXT 
+SAVE DC i Oe 
+NEXT DS OH 
“+ L 5, SAVE 
FLDI1 DC iad i 
FLD2 DC er ZO" 
END MAIN 








As you can see in the above example, the labels - SAVE and NEXT, were both generated each 
time the macro was called. This will lead to the problem of DUPLICATE LABELS. We take 
care of this problem by using &SYSNDX in the next example. 
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KAKKKKKKKKKKKKKKKKKKKKKKAK KKK KKK KKK KKK KR KKK KK KKK KKK KKK KK KKKEKEKEKEEK 


* 
* 


second Example: uses &SYSNDX to resolve the duplication 
problem caused by the first example 


* 


* 


KAKKKKKKKKKKKKKK KKK KKK KKK KK KKK KK KKKKKKKKKK KK KK KKK KKK KKK KKKKEE 


MACRO 
& LABEL ADD &NUM1, &NUM2 
& LABEL oh Dp DAVESGCYSNDX 
L 5, &NUM1 
A 5, &NUM2 
ow k 5, &NUM1 
B NEXT &SYSNDX 
SAVE&SYSNDX DC Fr—]' 
NEXT&SYSNDX DS OH 
L 5, SAVE &SYSNDX 
MEND 
MAIN CoBCrL 
ADD FLD1, FLD2 
+ So 59, SAVEOOO01 
+ L O7 Eis dL 
+ A D7 2 DZ 
+ ok Dy, Ebb 
+ B NEXTOOOL] 
+SAVEOOOL] DC | ee Ole 
+NEXTOOOL DS OH 
+ L 5, SAVEOOO1 
SUMLT PiD1, FiDZ 
+ SL 5, SAVEO002 
+ L ge al 
+ A oe om fy Be 
+ Sr Dig tt ab 
+ B NEXTOOO2 
+SAVEO0O002 DC | i 
+NEXTOOO2 Ds OH 
+ L Dy ODAVEVUOOZ 
FLDI1 DC Bo? 
FLD2 DC E20 
END MAIN 


As seen in this example we have taken care of the duplication problem. Now every time the 
macro 1s invoked the labels will be unique. But another minor problem caused now is the 
misalignment of the expanded code. This is caused by the fact that &SYSNDX is seven 
characters whereas its replacement is only four characters. This can be solved if we could 
somehow make &SYSNDX smaller. See the solution for this problem in the next example. 


Note: Mis-alignment will not cause any assembler or execution errors, it just doesn't look 
good. 
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KEKE KKK KKK RK KR RRR RRR KKK KR KR KERR KR KKK KK KEK KRKRKRKEK KK EKER K RK KES 


* 
* 
* 
* 
* 
* 
* 
* 
* 


& LABEL 


& NDX 
& LABEL 


SAVE &NDX 
NEXT &NDX 


MAIN 


++ ++ + 


+SAVEOOO1 
+NEXTOOOIL 
“+ 


+++ + 


+ 
+SAVEOO0O2 
+NEXTOOO2 
“+. 


FLD1 
FLD2 


Third Example 


MACRO 
ADD 
CLC 
SobITC 
‘sek 

L 

A 

‘op § 

B 

|B) @ 

DS 

L 
MEND 
ConCcr 


ADD 
yf 
ol 
DC 
DS 
ADD 
oy 
oT 
DC 
DS 
DC 
DC 


END 


same aS second example but shows a more 
sophisticated way of using &SYSNDX and 
solving the alignment problem. 


declared and assigned a value of 
"&SYSNDX'. Then &NDX can be used instead 


* 
* 
* 
* 
A local character variable &NDX is a 
* 
* 
of &SYSNDX, thus the remedy. x 

* 


KKK KKKEKK KKK RKKRKRREKRKRK KERR ERK KE KKK KKK KR KEKE KKK KERR KKK KRRK KKK KKK SE 


&NUM1, &NUM2 
&NDX 
"&SYSNDX' 
5, SAVE&NDX 
5, &£NUM1L 

5, &NUM2 

5, &NUM1L 
NEXT &NDX 
iis a 

OH 

DS, SAVE&NDX 


FLD1, FLD2 
5, SAVEOOOL 
oO, FisDlL 

oye LDZ 
D7 2 LDL 
NEXTOOOL 
la Ei 

OH 

5, SAVEOQOO1 


PLD», F 4DZ 
9, SAVEQOOZ 
27-2 GDL 

3,7 ELDZ 
Dy 2 sD 
NEXTOOOZ2 
ie 

OH 

5, SAVEOQOOZ 


aaa ee 
BZ" 


MAIN 
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&SYSLIST 


® Used to refer to any positional parameter in a macro definition, or also can refer to 
entry in a positional parameter sublist. 


O &SYSLIST(n) to refer to a positional parameter 
O &SYSLIST(n,m) to refer to sublist of positional parameter 


CALL3 EXMPL4 ONE, TWO, (R5,R6,R/,R8),,NINE, (R1) 


code in macro generated value 
S5Y5SLLST (2) TWO 

pop Gop ie Re lke 6 yao ms R7/ 

&SYSLIST (4) ahha mee 
SSYSbLo! (674) R1 


If a keyword parm should specify several values, enclose them in () but don't use &SYSLIST 
to refer to them. Use the variable name itself. 


MACRO 
SUBLISTS &P1, &KEY=(0,1,3) 
&P1 (1) DC F'&KEY(1)' 
Soro bor tis Zz) EOU &P1 (2) 
MEND 
MAIN Coe 
CALL SUBLISTS (HERE, THERE) , KEY=(5,6,7) 
+ HERE De | aie ae 
+ THERE EQU THERE 
END MAIN 


Other System Variable Symbols 


&SYSDATE To obtain date on which source module was assembled: MM/DD/YY 
fe &SYSTIME To obtain time at which source module was assembled hh.mm 


# &SYSECT - To generate the name of the current control section (CSECT in which 
macro 1s called) 


® &SYSPARM Lets you pass a character string into a source module from the JCL that 
invokes the assembler. 


A 














SET Symbols 


The LCLA, LCLB, and LCLC instructions may be used to declare and assign initial 
values to local SET symbols. Any variable symbols so declared is local to the macro- 
definition in which it 1s declared. The same variable symbol may not be used as a 
formal parameter and as a SET symbol in the same macro-definition. 


The GBLA, GBLB, and GBLC instructions serve to declare and assign initial values to 
global SET symbols. All local and global SET symbols must be declared in each and 
every macro-definition that uses the SET symbol. Whereas a local SET symbol is 
initialized each time the macro 1s used. Thereafter, the global SET symbol 1s said to be 
global through the entire assembly. 


Used to define and assign values while the macro Is processing. 
There are three types of SET symbol: 

a. Arithmetic 

b. Binary 


c. Character 


These variables can be declared as: 


O Global: Initialized the first time and then values are saved from one call to 
another. 
O Local : Reinitialized for each call. 


All the Set Symbols must be declared right after the prototype statement. Also, all 
Global symbols must be declared before Local Symbols. 


GBLA, GBLB, GBLC are used for declaring global variables 

LCLA, LCLB, LCLC are used for declaring local variables. 
Arithmetic SET Symbols 

32 bit field 

Value can range from -2”' to 2°'-1 


GBLA symboll,symbol2.... set to zero first time then maimtain old 
value from the last invocation of the macro 


e.g. GBLA &CNT1, &CNT2 
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* LCLA symboll,symbol2... set to zero every time macro 1s invoked 
e.g. LCLA &CNT1, &CNT2Z 


s SETA instruction is used to alter value of an arithmetic set symbol 


symbol SETA arithmetic expression 


for example, 


&CNTR SETA 1 init &CNTR to lL 
&CNTR SETA &CNTR+1 add 1 to &CNTR 
&CNTR SETA &CNTR* 5 multiply &CNTR by 95 


kk KKK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KK KE KKK KEKKEKKKEK KEKE KEKE KEKE KH 


The following two MACRO examples illustrate the use of is 
Local and Global arithmetic variables. = 
* 
In effect both the macros generate the 16 register equate * 
statements. a 
* 
First Example : uses a Local arithmetic variable - 
* 


Second Example: same as first example but instead of local” 
variable a global variable is used - 

* 

NOTE: These two examples also use conditional assembly & ™* 


concatenation which are discussed in detail later. * 


* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
* 
kk eK KK KKK KKK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KE KKK KEKKEKEKKKKKKKEKEKAKEK KK 


bao 





> ay. ie ae, Sie. fair « ie, Ge, Te ae. Se, Oe, ae ae a, ae, Se ae ae a ae ee i a ee ee, ee a ee, a ee, ee ee ae, a ee, ee Se a ee, es er, i a a3 








x First Example uses a Local arithmetic variable - 
KKK KKK KK KKK K KKK K KKK KK KKK KKKKKKEKKK KKK KKKKKEKEKEKKKEK KH 
MACRO 
& LABEL EQUREGS 
LCLA & REG 
mG 6 (6) = AL? (&REG GT 15) .ENDLOOP 
j R&REG Bou & REG 
&REG SETA &REG+1 
AGO s00OF 
-ENDLOOP ANOP 
MEND 
MAIN Gro Gull 
EQUREGS 
+RO KOU 0 
Pie KQU if 
+R2 FOU Z 
TRS KOU 3 
+R14 KOU 14 
TRL KOU Lo 
EQUREGS 
+RO OU : O 
+R1 EQU i 
q PZ KOU Z 
) TRS EQU 3 
+R14 KQU 14 
pa el Rs KQU Hite. 
END MAIN 


As you can see above, EQUREGS was called twice and the statements were generated both 
the times. This problem can be solved by using a global variable as shown in the next 
example. 
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» See. aie. dae > Sr. i ae, Sa. ee ae ae, Se, ee ee er ee, ae er, a, a. ae ae, a a ae a Se ae a, ae ee, ee, ie ee, ee, Se ae ie ae ee ee. ee, a er ie ke dee a 


* * 
* Second Example : uses a Global arithmetic variable and thus* 
= solves the problem of unnecessary expansion* 
x * 
* Note: This 1s not the only application of Global Variables * 
* * 
>. iy, Se, ty, ae, See, Tae ae a et. a, ee, ee ae a, a, Se, i a, ae i ee a er ae a ee rir a a a ye i ee ee, a i a ea i a, a 


MACRO 
& LABEL BEOQUREGS 
GBLA & REG 
. LOOP AIF (REG GT 15) .ENDLOOP 
R&REG EQU & REG 
& REG SETA &REG+1 
AGO . LOOP 
.ENDLOOP ANOP 
MEND 
MAIN Corr 
EQUREGS 
+RO- EOU QO 
+R1 OU i 
+R2 EQU Z 
+R3 EQU 3 
+R14 EQU 14 
+R15 EQU jie. 
EQUREGS <<<ss= this invocation does 
END MAIN not generate anything 


As you can see, nothing was generated when the macro was invoked the second time, since 
after the first invocation value of & REG was 16 and was never reinitialized to 0. 
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Binary SET Symbols 


* One bit field, can only have two values - 0 or 1 

* generally used as flag 

® GBLB &BIN set to zero first time then maintain old value 
s LCLB &BIN1 set to zero everytime macro is invoked 

* SETB instruction 1s used to alter the value of a binary set symbol 


symbol SETB logical expression 


&BIN1L SETB - 
&BINZ SETB (&SYM LT 7) if true &BIN2=1 
&BIN3 oE IB ('&SYM1' EQ 'NO') if true &BIN3=1 


KK KKK KKK KKK KKK KK KKK KKK KK KEKE KKKEKK KKK KEKE KEKE KEKE KKK KKK KKH 


* The following MACRO example is the same as the one used for* 
* illustrating the use of Arithmetic variables. = 
* K 
x* Here instead of using a Global arithmetic variable we are * 
* using a global binary variable as a flag to keep track of * 
* whether the macro has already been invoked. ~ 
KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KEKE KKK KEKE KEKE KEKE KKK KKH 
MACRO 
& LABEL EQUREGS 
GBLB + #£.&FLAG 
LCLA & REG 
AIF (&FLAG) .NOTAGAN 
& FLAG SETB 1 
. LOOP AIF (GREG GT 15) .ENDLOOP 
R&REG EFQU & REG 
& REG SETA &REG+1 
AGO . LOOP 


-ENDLOOP ANOP 
.NOTAGAN ANOP 


MEND 
MAIN OFS) 5 Oak 

EQUREGS 
+RO EOQU Q 
aa oo KOU 1 
+R2 EOQU Z 
+R3 EQU ° 
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+R14 EQU 14 


+R15 EOU ies. 
EQUREGS <<<ss= this invocation does 
END MAIN not generate anything 


Character SET Symbols 


Used for character strings needed during macro processing 


The string length can be 0 to 255 characters (if length exceeds 255, truncation occurs 
on the right hand side) 


Character strings can be created by: 


O string data- ‘AB' 
O a combination of character set symbol and string data - '&CHR1.ABC' 
O a combination of two character set symbols - '&CHRI&CHR2' 


GBLC &CHR1,&CHR2_ - set to null string first trme and never reinitialized 
LCLC &CHR1,&CHR2 - set to null string every time macro 1s invoked 


SETC command is used to alter the contents of a character set symbol. 


symbol SETC ‘character string’ 


MACRO 


& LABEL MOVEIT &REG, &RECEFLD, &SENFD 


LCLC &NDxX 


&NDX SETC ‘&SYSNDX" 

Bi X &REG, MOVE&NDX 

i ARND&NDX 
MOVE &NDX MVC 0(0, GRECFLD) , 0 (&SENF'D) 
ARND&NDX DS OH 

MEND 


We have already seen an example of using character set symbols (third example for 
&SYSNDX); will see some more later on. 
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Concatenation Rules 


When character strings are to be concatenated special consideration has to be made when the 
concatenated string is not a set symbol but string data. There must be something to indicate 
the end of the variable and start of the string. 


Let us take a look at the following two examples of concatenation (In both the examples a 
string 'ABCD' is concatenated to a set symbol): 


ie 'ABCD&CHRI1' < -- CORRECT 
Z; '&CHRIABCD' < -- WRONG 


In the second type how will the macro processor know that the name of variable is &CHR1 

and not &CHRIABCD, 1.e. we must have some kind of delimiter to indicate the end of set 

symbol. In the first type ' &' acted as as a delimiter for the second one '.' must be used as a 
delimiter, so the proper way to code the second type would be 


'&CHR1 . ABCD' < -- CORRECT 
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yee ae, ae oe, ae ae ee ee ee ee ee ee ee ee ee a ee ee ee ee Se Se ee ee, Se ee, ee 


The following example just shows how the concatenation 
will work under various circumstances. 


It also illustrates the use of character set symbols. 


Note: Don't look at what the generated assembler code does 


* 
* 
* 
* 
* 
x 
* 
* 
* 
zs just see what 1s being generated. 
* 

* 


x 
* 

* 

* 

* 

* 

In effect this macro will just generate some DC statements. * 
* 

x 

3 

* 

* 


Kode ee tee KKK KKK KKK KEK RR RK KK KRREKKRKKRKREKRRREKRKRKRRRRRE RRR KR KER KEK KKK KEKE XK 


MACRO 
& LABEL GENDCS 
LC iC &CHR1, &CHR2, &CHR3, &CHR4, &CHRS 
&CHRI1L net rl @ "ABCD' 
&CHR2 7 pl i ri Zo 
eCHRo SETC "SCHR. AY Zi" 
&CHR4 SBTC 'XYZ&CHR2Z&CHRL' 
&CHRS od a be @ "&CHR].&CHR2..EFGH' 
DC Cac." 
DC cS one 
DC C* SCHR" 
DC C'&CHR4 ' 
DG C @¢CHRS.” 
MEND 
MAIN CoBGs 
GENDCS 
DC 2 nee" 
DC C'1234' 
DCT C'ABCDXYZ' 
DC C'XYZ1234ABCD' 
DC C'ABCD.1234.EFGH' 
END MAIN 
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MNOTE and MEXIT 


Frequently, it 1s necessary to generate messages during macro processing. Some times 
messages are just informative and at other times they could be error messages and must be 
considered as assembly time errors. | 


* MNOTE can be used to generate messages along with an optional severity code. 
O Severity code determines whether the generated message is an error or just 
informative. 
O Message with severity code of 4 or higher is considered to be an error message. 
MNOTE 4, 'message' ==> 4,message 
MNOTE "message ' ==> message 
MNOTE 12, 'message' ==> message 
® MEXIT provides exit point from inside the macro body. 
O MEXIT must be used whenever macro processing has to be stopped in the 
middle. 


* All the following examples will incorporate the use of MNOTE & MEXIT. 
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Conditional Assembly 


6 Provides a way to alter the sequence in which source program statements are processed 
by the assembler. 


s Can branch within the macro to generate different code depending on different 
requirements and requests. 


« Conditional assembly statements are not generated when macro expands. 


2 Labels used in conditional assembly instructions are referred to as Sequence Symbols. 


Sequence Symbols 


* Naming convention of Sequence Symbol : 


.<alphabetic> <0-6 digits/letters> 


s Sequence Symbols are used in operand field of conditional assembly branch instruction. 
* You cannot put a sequence symbol on any assembler instruction which may be 
generated. 


Various conditional assembly instructions are: 


sequence symbol AIF <logical expression> sequence 
symbol 
sequence symbol AGO sequence symbol 
sequence symbol ANOP <== just like DS OH in 
assembler 
MACRO 
EQURGS 
GBLA &CNTR 
. LOOP AIF (&CNTR EQ 15) .ENDLOOP 
R&CNTR EQU &CNTR 
& CNTR SETA & CNTR+1 
AGO . LOOP 
.ENDLOOP ANOP 
MEND 


Note: .LOOP and .ENDLOOP are sequence symbols. 
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The following example illustrates the use of conditional 
assembly instructions and it also illustrates the use 
Of MNOTE and MEXIT commands. 


page but the macro expansion is not shown and is 
left as an exercise for you. 
feel of the macros. 





Do it to get a better 








* * 
* * 
* * 
* * 
* * 
* Note: The CSECT which invokes this macro 1s on the next ms 
* * 
* * 
* * 
* * 
* * 


KKK KK KKK KKK KKK KKK KEKKKKKKKKKKKKKKKHKKAKKKKEKKEKAaEKAEKKEKEKKKKK IKKE HK 








MACRO 
& LABEL BXITLINK &TYPE 
AIF ('&TYPE' NE '!') .FOUND 
MNOTE 'x***x*k MISSING TYPE PARAMETER' 
MEAXILT 
sb OUND ANOP 

ALF ('&TYPE' EO '‘'N') .NORMAL 
ALF ("&TYPE' EQ '‘'R!).RETURN 
AIF ('&TYPE' EO 'V"') .VALUE 
ALF ("“STYPE" 5O *3B”") «BOIH 
MNOTE EPs LNW Ait VAIO FOR TYPE 7ee x" 
MEA LT 

-.NORMAL ANOP 
L eS re oe Ge a 8 PICK BACKWARD POINTER 
LM Lay ep de CS) PICK ALL REGS 
BR 14 RETURN TO CALLER 
AGO . DONE 

~RETURN  ANOP 
L LDy 4 (yo) PICK BACKWARD POINTER 
L Lg ket pele) PICK Abb REGS BACHPT 
LM Oy Lepee tio) REGISTER 15 
BR 14 RETURN TO CALLER 
AGO . DONE 

. VALUE ANOP 
L 1354713) PICK BACKWARD POINTER 
LM Lao toy L213) PLGKR Als) REGS BXCEPT 
LM pepe Se CLS) REGISTER 0O 
BR 14 RETURN TO CALLER 
AGO . DONE 

*BOLH ANOP 
L Og ey SD PICK BACKWARD POINTER 
L 14,12(,13) PICK ALL REGS EXCEPT 
LM dep dhe pee (LS) REGISTER 15 AND 0O 
BR 14 RETURN TO CALLER 

. DONE ANOP 
MEND 
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Macro Quiz 


Show the expansion of EXITLINK in each case: 


MAIN 


Cou 


BALTLINK Q 


EXITLINK 


BEXITLINK V 


EXITLINK N 


|p, Gi a! lat pe Bs fe 


BAL DGINK. 3B 


END MAIN 
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try to fill these 
blank areas 














Data Attributes 


® For each data element or instruction the assembler assigns attributes. 

* By specifying attributes in conditional assembly instructions the conditional assembly 
logic can be controlled. (It can control sequence and contents of the statements 
generated) 


T' - Type Attribute 


Indicates the type of data of the field assigned to the symbolic parameter when the 
macro 1s invoked. 


= If &PARM is a symbolic parameter on a prototype statement and T'&PARM is coded 
in the macro, the following table summarizes all the possible values that can be 
assigned to T'&PARM. 


Symbols for DC or DS statements Meaning 
A Address data 
B Binary data 
C Character data 


F Full word fixed point data 
H Half word fixed point data 
P Packed decimal data 
R A-data or V-data 
X Hexadecimal data 
Z, Zoned decimal data 
V V-data 
Symbols that name other DC, DS statements Meaning 
T Machine instr. 
J CSECT name 
M Macro instr. 
T EXTRN symbol 
W COW 2netr, 
Symbols used for macro operand only Meaning 
N self—-defining term 
O Omitted operand 
U Undefined 
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* * 
* The following example illustrates the use of TYPE * 
x @cUcrioute. * 
* * 


Ka K KKK KKK KKK KKK KKK KKK KK KKK KK KKK KK KKK KK KEKE KE KKK KKK KKK KK 


MACRO 
CHECKT &PARM1, &PARM2 
i Oa @ &CHR1, &CHR2 


AIF (T'&PARM1 NE 'O') .FOUND 
MNOTE '**** MISSING PARAMETER ****! 


MEAXLT 
. FOUND ANOP 
&CHR1L SETC T'&PARM2 
&CHR2 SETC T'&PARM1 
&CHR2 SETC ‘*&CHRZ2ZECHRI" 
DG C @£CHRz* 
MEND 
MAIN Gone Lr 


CHECKT TABLE, PLINE 


+ DC Gas 2 Oe 

TABLE DS 2O0OF 

PLINE |S @ ClazZ 
END MAIN 


L' - Length Attribute 


A numeric value equal to the number of bytes occupied by the data that 1s represented 
in the expression. 


The value of the symbolic parameter used with this attribute must be a label in the 
calling program. 


This cannot be used for checking a missing parameter. 


This does not give the total storage occupied, it just gives the length attribute value - 
check third invocation of the macro given below 
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* 
* 
* 
* 


The following example illustrates the use of LENGTH 
attribute. 


* 
* 
* 
* 


KKK KKK KKK KKK KKK KKK KK KKK KKK KEKKEKKKKKKKEKKKEKEKEKE KEKE KKEKEKEKEKKEKEKE EKER KKK KKK 


& LABEL 


MAIN 


+ 


PLINE 
TABLE 
TABLEL 


MACRO 
MOVE LIT 
MVC 
MEND 


CobCT 


MOVE LT 
MVC 


MOVEIT 
MVC 


MOVEILT 
MVC 

DS 

DS 


DS 
END 


&ABC, &XYZ 
&ABC. (L'&XYZ), &XYZ 


PLINE, TABLE 
PLINE (80) , TABLE 


PLINE, 80 
PiLLNE (0) 730 


PLINE, TABLEL 
PLINE (20) , TABLEL 


oa Fa es 
CL80 
4CL20 
MAIN 


In the first invocation the length attribute for TABLE is 80. 


In the second invocation length will be 0 because 80 is not a variable defined in the 
calling program. You will also get a message from the assembler. 


In the third invocation length attribute is 20. 4 is the multiplication factor and thus is 
not accounted as a part of the length attribute. 
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K' - Count Attribute 


Numeric value equal to the numbers of characters in the actual parameter being passed. 





If K'&PARM is zero, it means that the parameter is missing (no value assigned) 


KKK K KKK KEKE KEKE KKK KEKE KEKE KEKE KEKE KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KK 


rs = 
* The following example illustrates the use of COUNT * 
* attribute. * 
* * 


KKEKKKKEKKKKKKKKEKKEKKE KKK KE KKK KKK KEK KKK KK KKK KKK KK KKK KKKK KKK KKK KKKKHK 


MACRO 
& LABEL CHECKK & PARM1, & PARM2 
LCLA &CNTR1, &CNTR2 
AIF (K'&PARM1 NE O) .FOUND 
MNOTE "*XXMISSING PARAMETER***'° 
MEXIT 
. FOUND ANOP 
&CNTRI SETA K' &PARM1 
&CNTR2 SETA K' & PARM2 -2 
XPRNT =C&PARM2, &CNTR2 
LA 5, &CNTRI1 
MEND 
MAIN CSECT 
CHECKK JUNKY, '1 TOP OF PAGE' 
+ XPRNT =C'l TOP OF PAGE',14 
+ LA oS 
CHECKK WHATEVER, 'O DOUBLE SPACE! 
+ XPRNT =C'Q DOUBLE SPACE',15 
+ LA oes: 
END MAIN 
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N' - Number Attribute 


Number of operands in an operand sublist 
Use only in arithmetic expressions 


N'&SYSLIST will give you number of positional parameters on the prototype 
statement in a macro call 


N'&SYSLIST(m) refers to number of sublist entries in the mth operand. 


N' &PARM is the number of sublist entries in the mentioned operand 


qo KK KKK KKK KKK KKK KK KKK KKK KKK KKK KKK KKEKKEKKEKKEKEKKEKEKEKEKEKEKRKEKEKEKEKEKEKE KEKE IEEE 


* The following example illustrates the use of NUMBER " 
x gael ribuce. = 
KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKKKKKKKKKEKEKKEKEKEKKEKEKEKE KEKE KKK KE KEKE 
MACRO 
& LABEL ChHECKN & PARM1, & PARM2, &PARM3 
LCLA &CNTR1, &CNTR2 
LF OH He &CHR 
&CNTRIL nog op byt N'&SYSLIST 
&CNTR2 SETA 1 
mF 10) AIF (&€CNTR2 GT &CNTRI1) . DONE 
* 
oe THE FOLLOWING SETC COMMAND IS TO PICK UP 
.* THE PARAMETERS FROM THE PROTOTYPE STATEMENT 
* 
&CHR DEG &SYSLIST (&CNTRZ) 
DC A (&CHR) 
&CNTR2 SETA SCNTR2* 1. 
AGO OOP 
. DONE ANOP 
MEND 
MAIN CoECT 


COGN TABLE ,.mO1 > CAKD 


+ DC A (TABLE) 
+ DC A(EOT) 
+ DC A (CARD) 


CHECAN CARD, Or lpi LE 


+; BL A (CARD) 

- 5) Os A (OPTBYTE) 
TABLE DS Z20F 

CARD DS CL6vU 
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OPTBYTE Ds xX 


KOT DS EF 
E}ND MAIN 
® Similar logic can be extended to sub lists also. Try it yourself. 


kK KKK KK KK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KE KKK KKK KKK KEK KK 


The following example illustrates the use of generating a 
label and macro documentation. 


incorporate missing parameter check in every macro which 


uses symbolic parameters. 


* 

* 

* 

* Checking for missing parameter is not done here and in most 
* 

* 

* 

kK KKK KKK KKK KKK KKK KKK KKK KKK KK KKK KKKKKKKKEKEKEKKEKKKKEKKEKEKEKKEKEK KEKE KEKE KK 


* 

* 

x 

* 

of other the examples, but it is good practice to = 
* 

* 

x 


MACRO 
& LABEL CHECLBL & PARM1, & PARM2 
i: THIS MACRO GENERATES THE NECESSARY CODE TO ADD 
—o TWO NUMBERS 
r 4 
LCi & NDX 
& NDX roy shal a @ GO LONDA 
* SAVE THE REGISTER BEING CHANGED 
uh 2,RGSVENDX 
> 
L 2, &PARMIL GET THE CONTENTS OF FIELDI 
A 2, &PARM2 ADD CONTENTS OF FIELD2 
SL 2,&PARML PUT RESULT IN FIELDL 
x 
_ RESTORE THE REGISTER BEING CHANGED 
L 2,RGSV&NDX 
* 
B ARND&NDX 
RGSV&NDX DS F 
ARND&NDX DS OH 
MEND 
MAIN CobBG. 
B Sonu. <<<===== Refer to 
oo =o note on next page. 
SUM LE CHECLBL FIELDI1, FIELD2 
+* SAVE THE REGISTER BEING CHANGED 
+ ST 2,RGSVOOOL 
4+ * 
+ L 2,F LBELD1 
+ A ZZ, LGD Z 


ia 











+ OL 2, FP LEDs 


+%* RESTORE THE REGISTER BEING CHANGED 
+ L Z7 RGOVO002 
4+ * 
+ B ARNDOOOL] 
+RGSVOOO1 DS EF 
+ARNDOOOL] DS OH 

FIELD DC PO" 

|e i Se SB DC | een 6 

END MAIN 


In the previous example the generated documentation is very obvious and as you can see the 
macro documentation (.*) was not generated. Everything seems ok here but there is a problem 
which might have made you pull your hair if you didn't know about it. 


The marked instruction (B SUMIT) will give you an undefined symbol error. This is because 
once the macro expands the macro statement itself is nothing but a line of documentation. So 
the label SUMIT doesn't actually exist, thus the undefined symbol error. This problem is 
solved by making sure that the macro generates a label if the invoking statement has a label on 
it. See the corrected example below: 


MACRO 
& LABEL CHECLBL &PARM1, &PARM2 


* 


_* THIS MACRO GENERATES THE NECESSARY CODE TO ADD 
_* TWO NUMBERS 

* 

LCLC &NDX 

&NDX SETC "&SYSNDX' 

* 

_* ALL THE NECESSARY CHECKS HAVE BEEN DONE AT 

> THIS POINT. SO NOW WE CAN GENERATE THE LABEL, 
_* IF THERE IS NO LABEL ON THE INVOKING STATEMENT, 
* 


ONLY DS OH WILL BE GENERATED 


* 


& LABEL DS OH 


. SAVE THE REGISTER BEING CHANGED 
ST 2, RGSV&NDX 
* 
L 2, &PARM1 GET THE CONTENTS OF FIELD1 
A 2, &PARM2 ADD CONTENTS OF FIELD2 
ST 2, &PARM1 PUT RESULT IN FIELD1 
* 
* RESTORE THE REGISTER BEING CHANGED 
L 2, RGSVENDX 
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B ARND&NDX 
RGSV&NDX DS ie 
ARND&NDX DS OH 
MEND 
NOTE: Expansion of the macro is left for you to figure out. 


Additional Macro Example 


KKK KR KEKE KKK KEKE KEKE KEKE KKK KEK KK KKK KEKKKKK KKK KKK KKK KKK KKK KKK KKK KKK IEKKK 


* 
* 
* 
A This macro tests whether &SUM contains a label 
* 
ws representing an address or a register in parenthesis. 
* 
ig &SUM 1s the place where the result of the addition 
* 
- Will be: Stored. 
* 
* 
* 
KREKKKKKEKRKKKKEKEKKEKEK KEKE KEKE KKK KKK KKK KKK KKK KKK KKK KK KK KKK KKK KKK KKKKKHK 
* 
MACRO 
& LABEL DORE & TABLE, &SIZE 
LCL & INREG 
LCLC &NDX 
&NDX SETC 'GoLoNDx* 
AIF ("&TABLE' NE '!') .CHKSIZE 
MNOTE 12, '*** TABLE OPERAND IS MISSING ***! 
MEXIT 
-~CHKSIZE ANOP 
AIF (K'&SIZE NE OQ) .CKLABEL 
MNOTE LZ,’ *** SIAR OPERAND 21S MISSING ***" 
MEXIT 
.CKLABEL ANOP 
AIF (T'&LABEL EQ 'O0O') .NOLABEL 
& LABEL DS OH 
-.NOLABEL ANOP 
ST 1,RGSV&NDX 
STM 14,15,RGSV&NDX 
& INREG Sd 'NO' 
ALF ('&TABLE' (1,1) NE '(') .NOTREG 
ST & TABLE (1) , PLST&NDX 


14] 














& INREG 
. NOTREG 


PLST&NDX 


. ACON 


. PARMSIZ 


RGSV&NDX 
CALL&NDX 


hop ie le @ 
ANOP 
CNOP 
BAL 
ALF 
DC 
AGO 
ANOP 
Be 
ANOP 
DC 
DS 
EOU 


BALR 


LM 
MEND 





ab Ar 


0,4 

1, CALL&NDX 

('&INREG' EQ 'NO') .ACON 
A (Q) 

- PARMSIZ 


A (& TABLE) 


A(&SIZE) 

3A 

* 

Loy =V (MY SORT) 
14,15 

1, RGSV&NDX 
14,15,RGSV&NDX+4 
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MACTEST 


* 


FIRST 
+FIRST 


++ +++ + 


+RGSVOOI11 
+CALLOOILIL 
+ 


+++ 


+++ + + 


+PLSTOO12 
+ 


+RGSVO0OO012 
+CALLOO12 
ot 
+- 
+ 
+ 


* 


So) Oak 


standard linkage goes here!! 


SORT 
DS 
ol 

o IM 
CNOP 
BAL 
DC 
DG 
DS 
BEQOU 
L 
BALR 
L 

LM 


LA 
SORT 
ol 

5 IM 
oul 
CNOP 
BAL 
DC 
8, w 
DS 
EOQU 
L 
BALR 
iF 

LM 


SORT 


TABLE, TBLSIZE 

OH 

1,RGSVOOILL 
14,15,RGSVO011+4 
O,4 

1,CALLOOIL1L 

A (TABLE) 
A(TBLSIZE) 

3A 

* 

15,=V (MYSORT ) 
14,15 

1,RGSVOOI11 
14,15,RGSVOO0O11+4 


RO, TABLE 
(RS) , TBLSIZE 

Le RGSVO0LZ 
14,15,RGSVOO012+4 
RoygPuo lUOLZ 

O,4 

1,CALLOO12 

A (QO) 

A(TBLSIZE) 

3A 

* 

15,=V (MYSORT) 
14,15 

1,RGSVOO12 
14,15,RGSVO0012+4 


TABLE 


+ 12,*** STZE OPERAND IS MISSING *** 


* 


SORT 


pi Dla 


+ 12,*** TABLE OPERAND IS MISSING *** 
exit linkage goes here!! 


* 





TABLE pC BE Zep 52 yee leo Oooo, Oo 
TBLSI2ZE DG ao Mi 
Plone 
=V (MYSORT) 
DROP 
MYSORT CSCI 
BR R14 


END MACTEST 
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Appendix A - Search Algorithms 


Linear Table Search 


Notes: This algorithm assumes that routine has received the table beginning and ending 
addresses. 


One line of pseudocode may be several lines of assembler code. 


READ A SEARCH REQUEST 
DO WHILE (NOT END OF FILE) 
SET A POINTER TO THE BEGINNING OF TABLE 
DO WHILE (NOT END OF TABLE AND ENTRY NOT FOUND) 
INCREMENT TABLE POINTER 
E.NDDO 
LP (ENTRY IS FOUND) 
PROCESS THE FOUND ENTRY 
PRINI THE NECESSARY DETAIL LINE 


ELSE 
PRINT "KEY NOT FOUND MESSAGE" 
BRNDIF 
READ NEXT REQUEST RECORD 
E.NDDO 


Binary Search 


BINSRCH (SRCHKEY, TAB@, EOT, RET) 


FOUND FLAG = 'N' - HI TOP SUBSCRIPT 
DO WHILE (HI GE LO AND FOUND FLAG = 'N')  - LO LOW SUBSCRIPT 
MID = (HI + LO) / 2 <-~-- ONLY USE INTEGER 

IF (ENTRY FOUND) 
FOUND FLAG = 'Y' 
ELSE 


IF (SRCHKEY > MIDDLE KEY) 
LO = MID + 1 


ELSE 
HI = MID - 1 
ENDIF 
ENDIF 
ENDDO 
IF FOUND FLAG = 'N' 
PRINT ERROR MESSAGE 
ELSE 
PRINT SUCCESS MESSAGE 
ENDIF 
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Hashing, 
NOTE: Read pages 194-195 of your textbook carefully. 
A brief explanation of hashing follows: 


In your linear search assignment, you filled the table sequentially and when a record was to be 
processed, you searched the whole table until the requested entry was found. That process can 
be referred to as linear search. For large tables, linear search would be a waste of time. So 
instead of using linear search, random search is used. Hashing is one of many ways to 
incorporate a random search. 


The basic idea of hashing is to take a key and convert it through some fixed process to a 
number in the range from 0 to n-1, where n is the maximum number of slots in the table. The 
resulting number can then be used to determine which entry in a table should be used to store 
the data item associated with the key. When a record needs to be retrieved, the same function 
must be used to calculate the slot number and find the requested record directly. 


Trouble occurs, however, when two keys hash to the same table entry. This situation is called 
COLLISION. Since only one key-data pair may be stored in an entry of the table, it is 
necessary to find another location for the second (or subsequent) key-data pairs hashing to a 
particular entry. 


Linear Probe: Collision problems can be solved by linear probe. If collision occurs, a 
linear search is done to find the next empty slot, where the current entry 
may be stored. 


Wrap Around: If physical end of table is reached during the linear search, the search 
continues from the top of the table. A table 1s not considered full until 
you come back to the point where youstarted from. 


Hash Function: The function used to calculate the table entry number. Same function 
must be used whenever referring to entries in that table. 


There are many ways of hashing a key to determine the correct table slot into which an entry 1s 
to be stored or from which an entry is to be retrieved. The hash function for this program 
should produce a hash value in the range 0 through 29, which will accommodate a table of 
exactly 30 slots. 


Hash values are similar to subscripts in that they both represent an ordering of entries. For a 


table with 30 slots, a subscript can range from 1 through 30, compared to the hash value range 
of 0 through 29. 
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A hash value multiplied by the length of an entry yields the displacement of that table slot 
from the beginning of the table, which 1s also the index for that slot. 


Hash Search 


HASHSRCHE (SRCHKEY;, RET) 
CALL HASH ROUTINE 
CALCULATE TABLE ENTRY ADDRESS (SLOT ADDRESS) 
(HASH VALUE * ENTRY LENGTH + BEGINNING OF TABLE 
SAVE DISPLACEMENT 


RC = -l SET THE RC TO NEG. ONE 
DO WHILE (RC = -1) DO WHILE RC IS NEG. ONE 
ITF (TABLE ENTRY = QO) ITF EMPTY SLOT FOUND 
RC = 4 SET THE RC FOR EMPTY SLOT 
RETURN TABLE ADDRESS 
ELSE 
IF (TABLE ENTRY = SRCHKEY) IF MATCHING KEY ARE FOUND 
RC = 0O SET THE RC FOR MATCHING KEYS 
RETURN TABLE ADDRESS 
BK LOE 
INCREMENT TABLE POINTER 
IF (BOT) TF END OF TABLE 
WRAP AROUND TO THE BEGINNING 
ENDIF 
IF (TABLE POINTER = SAVE DISP.) IF TABLE IS FULL 
RC = 8 SET RC FOR TABLE FULL 
ENDIF 
ENDIF 
ENDIF 
ENDDO 
NOTES : RC = O - Entry found in the table 
4 - Empty entry found, key not in table 
8 - The table was full 
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Example: 


QO ! 230 ! 
ee eee eee ee Hash function: Divide by 10 and 
1 ! 325 ! take the remainder (REM) 
se at eased a apetond ae eee DISP = REM * ENTRY-LENGTH + TABLE-ADDR 
2 O00 ! 
3! O00 ! BUILD SEARCH 
sid lee gece eis wine eel ee ee 230 S25 
4 ! O00 425 230 
ses eles sep ee eee eh ee 888 328 
> ! 425 ! 369 
ee 8s: 
6 ! OOO 
7 4 O00 ! 
Ss! 888 
9 ! 369 . 
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Appendix B - Sort Algorithms 


Bubble Sort 


Description: 
A table of records is sorted in ascending order by key. 


The keys of the 1* and 2" records are compared and records exchanged if out of order. 
This continues with the 2" and 3", 3" and 4", etc., until the largest key is at the end. 
The index of the final exchange is saved, as all records past it are in order. 

If no exchanges took place, all records are in order and the sort is complete. 


This process is repeated for the “sub-table” which ends at the saved index, again and again, 
with the index decreasing each time, until no exchanges take place, and the sort is complete. 


Algorithm: 


The following bubble sort algorithm is taken from Sorting and Searching, 2" Edition, by 
Donald E Knuth (Volume 3 in the series The Art of Computer Programming), p. 107. 


Algorithm B (Bubble sort) - Records R,, ... Ry are rearranged in place; after sorting, their 
keys will be in order K,<...<K, 


BI. [Initialize BOUND.] Set BOUND <— N (BOUND is the highest index for which the 
record is not known to be in its final position; so we are indicating that nothing is 


known at this point. ) 


B2. [Loop on j.] Set t <— 0. Perform B3 for j= 1,2,...,BOUND-1, then go to B4. 
(If BOUND= 1, this means go directly to B4.) 


B3. |[Compare/exchange R; : R 1.) If K; > K;, , interchange R, <—> R,,,, and set t <— j 


B4. —_ [Any exchanges?] If t= 0 terminate the algorithm; else set BOUND <— t and return to 
Step B2. 


Pseudocode for Algorithm B: 


Note that step B4 above is split here into steps 3 and 12 in order to make the code structured. 
(Reorganizing an efficient algorithm like this can introduce points of reduced efficiency, but 
this must be weighed against improvements in readability and understanding. ) 
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1 BOUND = N 
2 T= 1 Make Do While work the first time 
3 Do While ( T NE O ) Stop when no exchanges last time 
4 T = 0 Set “no exchanges so far” 
5 For ( J=l to BOUND-1 by 1 ) WhileJ < BOUND 
6 K=J+1 
| LE KEY td) > REY) 
8 Exchange REC(J) with REC (Kk) 
9 T= J Remember the exchange 
10 END 
ae END 
LZ BOUND = T Highest J of any exchange this time 
ES END 
Example: 


Here are the first few steps to sort 10, 1, 9, 2, 8, 3, 7, 4, 6, 5. 
J and B represent the J and BOUND of the pseudocode. 


10 1 9 2 8 5 a 4 6 5 
B 
1 <-> 10 
J 9 <-> 10 
J 2 <-> 10 
J 8 <-> 10 
J 3 <-> 10 
J 7 <-> 10 
J 4 <-> 10 
J 6 <-> 10 
J 5 <-> 10 
J 
A 9 Z 8 > | 4 6 a. 10 
B 
1 <-> 9 
J 2 <-> 9 
J 8 <-> Q 
J 3 <-> Q9 
J 7 <-> 9 
J 4 <-> Q9 
J 6 <-> 9 
J 5 <-> 9 
J 
1 Z 8 3 ] 4 6 5 9 10 
BCC... 


The program listing on the next pages is an example of an implementation. 
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OS | 


x PE | 
1G‘9'p’L'€'8'7'6' TOT. Od aTaWL Ze TO000000WO000000 #90000 
aIdWL Ut SeTtzjuse FO TEequnNn :OT. Od ZNNOD TE W0000000 090000 
x Of 
qyuNnoDS pzooer FO SSSAppYV (LNQNOD) ¥ Od 62 09000000 0S0000 
aTGWL JO ssezppw (ATAWL) W Od WaWd'TanNd 82 79000000 8S0000 
HOT Sd SOdaAGAWS LZ 8T0000 
x 92 
TETTeO Of urNAeyY PT Wa V4 a4L0 #~T0000 
x PC 
eTqez pezios Aetdstq OP‘aTaWL dwndx EZ p9000 8zZ00 #904 0904 400000 
x CC 
eTqeQ3 eyy 4310S OH aTaand’ Ot ‘Twa TZ 28000 2804 OWShP WO0000 
AIGaGnd TOF szeqeuezed yey Wawd Tand ’ T WI 0Z 85000 8S04 OTTP 900000 
x 61 
eTqe} peqjzosun Aetdstq Op‘ ATawL dwndx 8T y9000 8200 #904 0908 000000 
x LT 
zeystbez eseq suTjeq GT‘LSSLTaNa ONISN 9T 000000 
LOaSsS LSALTand ST 000000 
x PT 
TTT TTTTTTTET TTT TET TCT CTT CTT CTT TCT TTT TTT TT TLL eee 
x CL 
‘eTQeQy SU UT SPIOMTTNF FO QuNood syA pue ‘pseqRrOS eq OF x TT 
eTqeqi e Jo ssezppe 9syj yt BHbButssed ‘qiqana stTeo ATdwts sutynozr styuL » OT 
* 6 
(‘eTqeq oyj eqetTndtuew of ’‘9R7e ‘ZS ‘TI se Yyons ‘suoTtzonaysut » 8B 
Azeutq jzutod-pextz ey ATuo esn OF SN SMOTTE STULL) ‘sures BYR STB » L 
Key 3220S |yuy pue pxz0deAT syQ ‘seSsed STYyR UL ‘“SpAOMTTNF FO STqezZ e& - Y 
4320S OF SUTANOA 3220S eTqqnq e Fo ssn syA sejezqQsuOWwep wexzbord styuL -»«* ¢ 
x P 
SCS TCT CTT TT TTT TT ET TTT TT TT TTT TTT TT TTT TTT TTT eee Tt ee 
x 2 


LNEWELVLS BOUNOS JLWLS zuaaqw Tudqw g3q0d LOaraoO 90T 
I aqovd uoTZeITAsSUOUINg IOS eTqQqng - 09E IDSO 


xxx9deq tosduod NIN 3 ATUN 3S UUeg Wor, XYdWNdD=SldO ‘O8TI=/OUL/MOSHO ‘OHDA=X/LddQS=SNI 06€/SO:PHd/ZL96 86/80/TO-Z¥/0°b LSISSY xx 





IS] 


‘fC -> ~L 3es pue (T+L)a <-> (L)4a 
ebueyorzequt ‘(tT+e)y < (c)u FI ((T+Le)a : (c)ua ebueyoxe/ezeduod) ‘Ea 
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Selection Sort 
Description: 


A table of records is sorted in ascending order by key. 


Beginning at the first entry, the entire table is scanned for the smallest key. 
The record with that key is exchanged with the first record in the table. 
(Now the first entry in the table contains the record with the smallest key.) 


This process is repeated for the “sub-table” which begins at the second entry, then the one 
beginning at the third entry, etc., until the final sub-table beginning at the next-to-last entry. 


Pseudocode: 


N represents the number of records REC in the table, each having key KEY. 
I is the index of the first entry in the sub-table being scanned. 

J is the index of the record with the smallest key found in this scan thus far. 
K keeps track of where we are in each sub-table scan. 


1 FOR ( 1I£=1to N-l by l ) I indexes the start of the sub-table 
2 J = I Assume first entry is smallest 

3 FOR ( K = I+l to N by l ) Scan sub-table for smallest key 

4 IF ( KEY(K) < KEY(J) ) Is this J a new smallest? 

5 J = K If so, remember it 

6 END 

7 END 

8 Exchange REC(I) with REC (J) Exchange first with smallest 

9 END 

Implementation: 


In order to implement this pseudocode in assembler, we have to “translate” the values used 
above. For example, we might expect to receive the following parameter list: 


PARMS DC A(TABLE) Address of table to be sorted 
DC A (@NAV) Address of a word with address of next 
* available entry 


(We’ll assume the length of an entry is known, and 1s in a fullword labeled ENTL.) 


There are a number of ways we might proceed. We could calculate an integer N by 
subtracting the address of TABLE from the address of the next available entry, then dividing 
by ENTL. Or, we could think of N as the last record in the table and calculate that address by 
subtracting ENTL from the address of the next available entry. The second method is more 
common, so we will use it, even though the pseudocode assumes N is an integer. 
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LM 
L 
Ss 


i FOR ( I 


CLC 
BNL 


LR 


DS 


END 


DS 


10,11,0(1) 
O,0(,11) 
0, ENTL 
0,N 

= 1 to N-1 by 1 ) 
9,10 


IN 
FORLEND 


I 
39 
( K = I+1 to N by 1 ) 


Jy 9 
7,ENTL 


7,N 
PORSEND 


IF ( KEY(K) < KEY(J) 


0 (4,7) ,0(8) 
IF4END 


7,ENTL 
FORS 


OH 


i ¥ 





Implementation of selection sort pseudocode. 


Get A(TABLE, @NAV) 

Get @ of next available 
Get @ of last entry 

Save address of last entry 


R9 = I 


All done? 
Branch if yes (I > N-1) 


R8 = J 


R/ = I 
R/ = I+l = K 


All done? 
Branch if yes (K > N) 


) Ex: key is first 4 bytes 


Is this a new low key? 
Branch if not, keep in order 


Else remember this new record 


K = K+t+l 
Continue 











+ + 


9 


* 





Exchange REC(I) with REC(J) Ex: record is 8 bytes long 


MVC TEMP; 0'(9) TEMP = REC (T) 
MVC 2659). 5018) REC (I) = REC (J) 
MVC 0(8,8),TEMP REC td) TEMP 


END 


9,ENTL IT = [+1 
FORI Continue 


WP 


FORLEND DS OH 


LoMP 
ENTL 


ibys F Number of records in table 
DS CL8 Temp for record exchange 
DC ao Length of a record 


Comments: 


It’s probably worth taking a few minutes to analyze how the assembler instructions 
were written to follow the pseudocode. In particular, note how the FOR statements are 
implemented as a test, with a branch to the matching END when the test fails. Also, 
the END statements associated with FOR are implemented in two parts 

a. The bottom of the loop, incrementing the appropriate index, followed by 

b. A label for the FOR to branch to 


The choice of N as a label was made solely for comparison with the pseudocode. 
Labels are normally selected to have information content (e.g., NUMREC). 


The use of ‘@’ is intended to imply the word ‘address. ’ 

The implementation had to assume two record characteristics: 

a. The length of the record 

b. The length and location of the sort key 

The record length was also placed in ENTL in order to simplify the example; the 


implementation you write may not need that storage location. 


Statement 8 of the pseudocode is always executed, even if the first record has the 
smallest key. This is OK, and simple, but not efficient. 


The sort is stable (equal keys remain in original order). 
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Insertion Sort 
Description: 


A table of records is sorted in ascending order by key, using a “bridge hand” process. 


Assume that 1 < j < N and that records R,, ..., R;_, have been rearranged so K, <...< KK. . 


Compare the new key K, with K,.,, K,, ... in turn until discovering that R, should be inserted 
between records R, and R,, ,; then we move records R;,;, ..., R,, up one space and put the new 
record into position i+ 1. (In the algorithm, the comparing and moving operations are 
interleaved. ) 


Algorithm: 


The following insertion sort algorithm is taken from Knuth, Sorting and Searching, p. 80. 


Algorithm S_ (Straight Insertion Sort) - Records R,, ... Ry are rearranged in place; after 
sorting is complete, their keys will be in order K, <...< Bas 


S1. [Loop on j. ] Perform steps S2 through S5 for j= 2,3,...,N then terminate the algorithm 


S2. [Set up i, K, R.] Seti <— j-1, K <— K;, R <— R, (in the following steps we will 
attempt to insert R into the correct position, by comparing K with K,, for decreasing i. 


S3. [Compare K : K;.] If K = K, go to step S5 (found the desired position for record R) 


S4. [Move R;, decrease i.] Set R,, , <— R,, i <— i- 1. If i> 0 go back to step S3. 
(If i= 0, K is the smallest key found so far, so record R belongs in position 1) 


S5. [R into R,;, ,.] Set R,, , <— R. 


Pseudocode: 
1 FOR ( J =2 to N by 1 ) 
2 I=J- 1 Records up to I are already sorted 
3 KEY = KEY (J) Key portion of record to insert at correct place 
4 REC = REC (J) Record to insert at correct place 
» WHILE ( KEY < KEY(I) AND I > 0 ) 
6 REC (I+1) = REC(T) Move I" record up if its key is larger than new one 
/ Les = | 
8 END 
9 REC (I+1) = REC Insert the new record and key at opened slot 
10 END 
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Appendix C - Merge Algorithms 


Note: These algorithms assume that the arrays to be merged are already sorted on ascending 
order of the key and the resulting array will also be sorted in ascending order. 


You might have to change the algorithms little bit depending on your requirements. 


Parameters Expected : Address of TABLE] 
Address of TABLE2 
Address of MERGED TABLE 
End of TABLE] 
End of TABLE2 
End of MERGED TABLE 


DO WHILE (NOT END OF EITHER TABLE) 
IF (TABI (KEY) < TAB2 (KEY) ) 
PUT TAB1 ENTRY INTO MERGED TABLE 
INCREMENT TAB] POINTER 
ELSE 
IF (TABI (KEY) > TAB2 (KEY) ) 
PUT TAB2 ENTRY INTO MERGED TABLE 
INCREMENT TAB2 POINTER 
ELSE 
PUT TABI] OR TAB2 ENTRY IN THE MERGED TABLE 
INCREMENT TAB1L POINTER 
INCREMENT TAB2 POINTER 
ENDIP 
ENDIF 
INCREMENT MERGED TABLE POINTER 
ENDDO 


(Now, at end of at least one table) 


DO WHILE (NOT END OF TAB1) 
PUT TABI ENTRY INTO MERGED TABLE 
INCREMENT TAB1L POINTER 
INCREMENT MERGED TABLE POINTER 
ENDDO 
DO WHILE (NOT END OF TAB2) 
PUT TAB2 ENTRY INTO MERGED TABLE 
INCREMENT TAB2 POINTER 
INCREMENT MERGED TABLE POINTER 
ENDDO 
RETURN ENDMERGE POINTER 
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Another Merge Algorithm 


MERGE (TAB1, EOT1, TAB2, EOT2,MERGE, ENDMERGE) 


DO WHILE (NOT END OF BOTH) 
IF (END TAB1) 
PUT B INTO MERGE 
INCREMENT TAB2 POINTER 
ELSE 
IF (END TAB2) 
PUT A INTO MERGE 
INCREMENT TAB1 POINTER 
BLSE 
IF (A < B) 
PUT A INTO MERGE 
INCREMENT TAB1 POINTER 
BLOE 
ITF (A > B) 
PUT B INTO MERGE 
INCREMENT TAB2 POINTER 
ELSE 
PUT A INTO MERGE 
INCREMENT TAB1 POINTER 
INCREMENT TAB2 POINTER 
ENDIF 
Ne 
ENDIF 
ENDIF 
INCREMENT MERGE POINTER 
E;NDDO 
RETURN MERGE POINTER 
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Appendix D - Log Sheets 


These log sheets are for the use of the student, to record information relating to work done in 
this course. There are three forms: 


ie 


Programming Assignment Log Sheet - To record due dates, verbal changes made by 
the instructor, and anything else related to the assignment. There is room for the eleven 
programming assignments of a typical semester. 


Grade Log Sheet - To record the grades received during the semester, on all 
assignments and tests. 


Abend Log Sheet - To record the various types of program abnormal termination the 
student has encountered, with an eye toward reducing the debug time for recurring 
abends. This may be the most useful of the three forms and their use may be required 
by the instructor. 
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Programming Assignment Log Sheet 


ASN # DUE ANY CHANGES MADE NEW TOPICS 
DATE IN ASSIGNMENT 








QUIZZES 


\O 
— 





HOMEWORK 


Grade Log Sheet 


PROGRAMS 


TEST 





ABEND CODE 


Abend Log Sheet 


CAUSE OF ABEND AND HOW IT WAS CORRECTED 
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Appendix E - Accessing the NIU Computers 


The followmg pages describe how to access and use the student computing facilities at NIU. More 


information can be found online at http://www. niu.edu/ acs/csci/labs. html, “Using the Student 
Computer and Communications Facilities. ” 
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COMPUTER SCIENCE QUICK ACCESS GUIDE 


The computer science labs are running Windows 98. For returning students, the login and password setting 


procedures are the same as last semester. For new students, use the following procedure to set up your account 
aCCess. 
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The Username field contains four sub-fields separated by periods. The periods must be kept. In the first sub- 
field, replace ZXXXXXY with your assigned Novell user’s id (called a Z-id). In the second sub-field, i.e, the 


final Y in the above example, replace Y with the last digit of your user’s id. The remaining data on the line is 
required. 


If this is your initial login session, use the last six digits of your social security number for the password. If the 
information is correct, you will shortly be prompted to change your Novell password. The Novell password is 
used for access to the Novell servers, the mainframe and your email. For the password to work on all systems, 


your password should be a combination of lower case alpha characters and numbers and be between 6 and 8 
characters long. 


If you encounter problems logging in, contact the lab aids. 

Once you have successfully logged in, wait a few minutes. Additional software will run and set up access 
appropriate to Computer Science. If you click on the start button and are presented with only two choices, the 
configuration software has not finished. 


One the configuration is complete, clicking on the start button should 
display a menu similar to the one at left.. 


Most users will work with the three choices in the top box. 
Computer Science provides access to software specific to Computer 
Science. | 
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COMPUTER SCIENCE QUICK ACCESS GUIDE 


. 


ACS maintains documents on the current configuration of NIU’s student labs and access software. To access 


the current documents, go to their web page at www.cs.niu.edu/acs/doc.html 
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Using the Student Computer and Communications Facilities 


This ACS version of this document can be found on the web under " www.niu.edu/acs/csci/labs. html ". 





Overview 


Identifying Your LogonID 

Your Password 

Accessing the File Servers from a Lab 
Using Windows 98 on a Lab Computer 
Viewing Web Documentation 
Activating Your Electronic MailBox 
Changing Your Course Directories 
Formatting a Diskette 

Closing Your Current Session 





Overview 


The personal computers in the student computer labs are connected on a communications 
network that provides access to general access file servers, the course-specific file servers, and 
printers. The general access file servers distribute the general productivity and communications 
software such as word processors, spreadsheets, presentation packages, electronic mail clients, 
and web browsers. These file servers also store student home directories, each with 10 
megabytes of storage space located on drive "F:". 


Access to the file servers, the software packages, and the printers is controlled by the Novell 
Directory Service (NDS) running on all file servers. Each student is identified within NDS 
through their unique student LogonID, which is known as their Z-Number (Z951234, for 
example). The student LogonID along with a password provides secure access to the servers, 
various software packages and the printers. For more information on your LogonID, see the 
section entitled " Identifying Your LogonID ." For more information on your password, see the 
section entitled " Your Password ." 


Whenever a personal computer in a student computer lab is started, it automatically connects to 
NDS. Once you have given NDS your LogonID and matching file server password, you are 
presented with a Windows 98 desktop with general student access. Starting applications and 
managing your files are done from the Windows 98 desktop or Start-menu. Windows 98 is set 
up to allow you to run only those applications previously installed on the file server by ACS. 
The specific selections will vary from lab to lab, but all labs contain a basic set of applications, 
such as Microsoft Office (word processor, spreadsheet, presentation, and database software), 
Netscape Communicator (internet web-browsing software), Eudora Pro (electronic mail 
software), and other programs. 


Remember to close your session (logout) when you are finished working. For more information 
on your closing your session, see the section entitled " Closing Your Current Session ." 








In addition to access to the file servers, the software, and the printers, you can connect to other 
computer systems that you may need for your assignments: the student electronic mail post 
office (students.niu.edu), web servers, news servers (news.niu.edu), and department systems such 
as the Computer Science Sun Unix system and the IBM S/390 mainframe. All of these systems 
are reached using communications applications within Windows 98. You also have access to 
your entry in the NIU Electronic Directory which displays your address, phone number, 
electronic mail alias, and other information about you on request. 


The student electronic mail server account and the IBM S/390 Mainframe both use the same 
LogonID and password as the file server (NDS). You can change your passwords whenever you 
like, but you are required to change your NDS password every 130 days (roughly each semester). 


NDS 


The primary account for use in the computer labs is the NDS account. This account allows 
access to the University network. Students log in with a proper combination of their LogonID 
and NDS password. Once logged into NDS, students then can select the specific course 
environment in which they wish to work. Logging into NDS also grants access to other accounts 
via the network and internet connection. 


The Student Electronic Mail Server 


Student electronic mail accounts are stored on a single server (students.niu.edu). Student 
electronic mail accounts are listed under the same Z-number as the NDS LogonID. Also, the 
student electronic mail account shares the same password as the NDS LogonID. The full account 
name for the electronic mail account is of the form zxxxxx@students.niu.edu. This account is 
primarily accessed in the computer labs through Eudora Pro or Netscape Messenger. 


The Computer Science Sun Unix system 


The Computer Science Sun Unix system (mp.cs.niu.edu) is accessible either through the Telnet 
application where the user issues Unix commands at the system command prompt, or through the 
FTP application where the user transfers files between the Unix system and the PC. Accounts on 
the Computer Science Sun SPARC are listed under the Z-number (LogonID), but the passwords 
are not synchronized with the NDS password. Users experiencing problems accessing the 
Computer Science Sun SPARC should contact the Computer Science department not ACS. 


The IBM S/390 Mainframe 


The IBM mainframe operating under MVS (mvs.cso.niu.edu) is accessible through the 
MVSBATCH application, which manages your file transfers (using the FTP application) between 
the MVS system and the PC. MVSBATCH is used to submit jobs to and retrieve output from the 
MVS batch queue. The files transferred to MVS can contain additional instructions for MVS. A 
standard ftp client can be used in place of MVSBATCH. Accounts on the IBM S/390 Mainframe 
are listed under the Z-number (LogonID), and the passwords are synchronized with the NDS 








password. 
The ph Nameserver 


The ph Nameserver maintains information that appears in the electronic phonebook. Accounts 
on the ph Nameserver are not listed under Z-number (LogonID). Instead, they are listed under 
your electronic mail alias. Furthermore, the ph Nameserver account password does not 
synchronize with the NDS password. More information on using the ph Nameserver can be 


found at http:/Awww.niu.edu/niu_ph.html . 
Identifying Your LogonID 


A unique LogonID (Z-Number, Z-#, or Z-ID) is created for each student when he/she is admitted 
to NIU. It is used to identify the student as a computer user. The LogonID stays the same during 
your enrollment at the University, and it will not change even if you take a short (one-year) 
absence before returning to the University. 


Various access privileges are attached to your LogonID each semester for which you register 
based on the courses you have enrolled in. 


The procedure below explains how you can obtain your LogonID at any time that you are 
registered with a simple phone call. 


1. Call (815) 753-8995 from a Touchtone phone. 
2. At the prompt, enter your student number (social security number) using the keypad. 


3. At the prompt, enter your T.R.A.C.S. registration PIN using the keypad. If you do not know 
your T.R.A.C.S. registration PIN, contact Registration and Records. 


4. At the prompt, select option #1 ("obtain your LogonID"). 


The LogonID is a matter of public record. You do not need to be concerned with attempting to 
keep it secret (unlike your password). However, it is useful to memorize since it is used 
consistently with so many systems (NDS, electronic mail, the IBM S/390 mainframe, dial-in and 
one-meg-modem access, and the Computer Science Sun SPARC). 





Your Password 


There is a single password that provides security for most of a student’s various accounts. This 
is the NDS password. In addition to authenticating the user into NDS, it also authenticates the 
user to the student electronic mail server, the IMB S/390 Mainframe, and for dial-in and 
one-meg-modem access. 


It is important that your password be kept confidential. Allowing another person to use your 


account or have access to your password could result in loss of data, revocation of privileges, or 
extreme embarrassment. 


Password Requirements 


Since the same password is used for three different environments, it is important that the 
password conform to the following guidelines. Failure to conform to these guidelines could 
result in an inability to authenticate to certain systems. 


1. The password must be between six (6) and eight (8) characters long. 
2. The password must contain at least one (1) number and at least two (2) letters. 
3. The password cannot have been used with this LogonID before. 


While it may be possible to enter a password that does not conform to these guidelines, such 
passwords are likely to cause problems when used on other systems. 


In creating passwords, do not use any of your names, your family's names, words or information 
that has been recorded anywhere with your name, or a word that appears in a dictionary or other 
listing. These are not secure passwords because all of them can be generated and automatically 
tested by a computer in a very short time. You can suffer the loss of your saved work or the 
embarrassment and cost of the damage caused by another masquerading as you. Good passwords 
are easy to remember so they need not be written down anywhere. The first letters of the words in 
a song, a Saying, or an advertisement make a good password. Mnemonics, acronyms, and 
abbreviations are also good choices. Be sure to include some numbers, a symbol, and both 
uppercase and lowercase letters. Replacing letters with look-alike numbers or symbols, such as 5 
for s and 6 for G, is effective 


Changing Your Initial, Reset, or Expired Password 


When your account is assigned, the initial password is set to the last six digits of your student 

number (social security number). The very first time you login, this is the password that you 

should use. The system will consider this a "grace login," and you must change your password 

within the next four login attempts. Furthermore, some systems may not accept this initial 

password. NDS will accept this initial password and will allow you to change it (unless your five 
"grace logins" have been used). 


After being set by the user, the password will be valid for 130 days. After this time, the user has 
five (5) "grace logins," during which they must change their password. During these "grace 
logins," the user will be prompted to change their password. If the user does not change their 
password by the sixth login attempt after the 130 days has expired, the account will be locked 
and the user will be unable to log into any of the services until contacting Academic Computing 
Services. 





When you are using a "grace login," you are given a chance to change your password before your 
personal computer displays the Windows 98 desktop. A "Confirm" dialog box with the 
following message is displayed: 


LOGIN-4.21-2023: The password for user Z987654 has expired. 
You have 5 grace logins left to change your password. 

Do you want to change your password? 

Continue? (Yes/No) Y 


When prompted with such a message, follow these steps to change your password. 
I. Select "Yes" or press Enter. A "Change Password" dialog box is displayed. 


2. In the "Enter new password:" box, enter a new password that conforms to the guidelines 
above. Your password is not displayed when you type it. 


3. Type your new password again in the "Retype new password:" box. Your password is not 
displayed when you type it. You can reselect the contents of either box and retype your 
password(s). 


4. Select "OK" or press Enter. 


When the two entries match, the file server accepts your new password with a "Your password 
has been changed" message and returns to the Windows 98 desktop. 


When the two entries do not match, the file server does not change your password but displays an 
"Error" dialog box with a "The passwords entered did not match" message. Select "OK" or press 
Enter to redisplay the "Change Password" dialog box and repeat this procedure. 

Should you forget your password or find that it is not working, you can call to have it reset. Call 
752-RSET (752-7738) and be prepared to provide them with your LogonID and your student 
number (social security number). They will provide you with a five-character password that will 


allow five "grace logins" for the user to change the password to one that confirms to required 
guidelines. 


Changing Passwords at Any Time 


A user can choose to change their password at any time. The following process describes the 
steps a user should go through to change their password before the 130-day limit expires. 


1. Click on Start. 
2. Select "User Utilities" from the Start-menu. 


3. Select "Change your network password" from the submenu. 











4. Confirm your identity by entering your old password when prompted and clicking "OK" or 
pressing Enter. 


5. Enter a new password when prompted, confirming to the restrictions outlined above. Click on 
"OK" or press Enter when finished. | 


6. Confirm your new password by re-entering it when prompted. Click on "OK" or press Enter 
when finished. 


7. You will receive a message that your password has been successfully changed. 
Password Problem Troubleshooting 


Password problems can be corrected by the ACS Help-desk in Swen Parson 120 between 
8:00AM and 12:00 NOON or between 1:00PM and 4:30PM Monday through Friday. The Swen 
Parson Operations Window (next to the output bins in Swen Parson) accepts requests for 
password changes at other hours. To get a new password, you must bring an ID card with your 
name and photo on it and be able to provide your LogonID. 


Accessing the File Servers from a Lab 


Access to the software on the file servers, your home and course-specific directories, and the 
printers is available as soon as your LogonID is active. You must be able to identify yourself 
(log on) to the file servers with your LogonID and NDS password. 


The following sequence of items describes the procedure to get access to the file servers, the 
software, the printers, and your directories. 


1. Ignore the "Type N to boot from Network" message if it appears. 


2. Type your full username in the "Username:" box. The template ".Z9XXXY.Y.students.niu" 
for your full username has been placed in the box. Be sure that you start your full username with 
a period, replace the "Z9XXXXY" with your LogonID, for example, 2987654 (the Z can be 
lower- or upper-case), and replace the "Y" between the periods with the last digit of your 
LogonID, "4" for our example. Therefore, the student with the LogonID of "2987654" would 
enter ".z987654.4.students.niu". For more information on your LogonID, see the section 


entitled " Identifying Your LogonID ." 


3. Press Tab or use the mouse to move the cursor to the "Password:" box of the dialog box. 


4. Type your current NDS password into the "Password:" box. The first time you log-on, the last 
six digits of your student number (Social Security Number) should be your password. Your 
password is not displayed when you type it (it is replaced on screen by a series of "*" marks), but 
you can reselect the contents of the "Password:" box and retype your password to make 
corrections. For more information on your password, see the section entitled "Your Password ." 


5. Select "OK" or press Enter. When you have properly typed your LogonID and NDS password, 
your personal computer is allowed to access those directories on the file servers for which you 
have been given permission. 


If you mistype your LogonID or password, the file server displays a "Netware Security Message" 
dialog box. 


The system could not log you into the network. 
Make sure your name and connection information are correct, then type your password again. 
Select "OK" or press Enter to redisplay the "Login" dialog box and try again. 


|. If this is the first time you have logged onto the file server or if your password has expired 
after 130 days from being set, you are asked to change your password. See the section entitled " 
Your Password " for details on how to do this. 


After you successfully enter your LogonID and NDS password, you are logged into a "General 
Application" session. In the labs set up for Computer Science, access to additional software will 
automatically be provided after a few minutes. 


However, your drive options are not associated with any particular course. Choosing a course 
primarily provides you with shortcuts (G:, H:, and so on) to the various section, instructor, and 
department directories for your specific course. You always have the shortcut F: pointing to your 
home directory on the file server. For more information regarding selecting a course to associate 
with your computing session, see the section entitled "Changing Your Course Directories ." 


1. Select the applications needed for your work by initially clicking on "Start" in the lower left 
corner of the screen to get a menu or by opening the icons along the left side of the screen. The 
Windows 98 environment for the NIU labs is described in the section "Using Windows 98 ona 


Lab Computer" . 


2. Use Netscape Navigator to view the lab documentation found on the web as described in the 
section " Viewing Web Documentation ." A copy of this document and other more extensive 
documents can be found on the web. 


3. If this is the first time you have logged into the file servers, activate your electronic mailbox as 
described in the section "Activating Your Electronic Mailbox ." You can activate your 
electronic mailbox at any time and you need only do so once. 


4. Remember that your Electronic Mailbox password is the same as your NDS password. 


5. Proceed to complete your work within the chosen course. Selecting another of your courses is 
described in the section " Changing Your Course Directories ." 











6. Close your session with the software from the file servers as described in the section " Closin 
Your Session ." These actions terminate your access to all the file servers until your next 
successful login. 


Using Windows 98 on a Lab Computer 


The icons on the left side of the Windows 98 screen and the menu items under "Start" provide 
similar access to software applications, files, and directories. The "General Applications" folder 
or menu item allows you to select generally available applications, including Microsoft Office 
(Word, Excel, PowerPoint, Access, and PhotoEditor), Netscape Communicator (Navigator, 
Messenger, and Composer), Qualcomm Eudora Pro, and Command Virus Protection. The 
"Program" folder or menu item includes course- or lab-specific software applications in addition 
to all the General Access applications. | 


The "My Computer" icon should be used for file management (finding, renaming, and copying 
files and directories). The "My Computer" icon contains a pointer to your home directory (F:) on 
the server as well as pointers to other directories associated with the course you may have 
selected to work on. Selecting another of your courses is described in the section "Changing 
Your Course Directories ." 


Deleted files and directories are saved for resurrection in the "Recycle Bin”. 


Remember that ACS does not back up student data. Please maintain copies of your data and other 
important information on your diskettes. All student directories on the file servers are purged at 
the close of each semester. 


The Eudora mailer can be used to check your mail and send messages. Netscape Navigator can 
be used to browse the Web, join newsgroups, check and send mail, and upload files to ftp 
servers. 


Viewing Web Documentation 


There is a variety of information about using the NIU computer and communications facilities 
that is published on the NIU web pages. This document and others like it are available from the 
Academic Computing Services web pages. Please consider "bookmarking" the documents rather 
than printing them as the documents change from time to time -- recent changes do not get placed 
in your printed documentation. 


1. Select the "Start" button in the lower left corner of the Windows 98 desktop to display the 
Start-menu. 


2. Select "General Applications" from the Start-menu. 


3. Select "Internet" from the submenu. 





4. Select "Netscape" from the submenu. 
5. Select "Navigator" to start the web browser. 


6. Type " http://www.niu.edu/acs/doc.html " in the "Location:" box and press Enter to go to the 
Academic Computing Services documentation pages. 


7. Read the material presented on screen by the browser. 

8. Click on the arrows on the right side of the page to move through the material. 
9. Double-click on the blue highlighted items to get additional information. 

10. Select the "Back" button at the top of the screen to return to earlier pages. 


11. Select "Bookmarks" from the menubar to mark a page of information for later 
reference.[jko6] 


12. Select "Add Bookmark" on the hanging menu to add a page to the displayed list of marked 
pages. 


13. Continue to read the information on these pages to find out more about your use of these 
Services. 


14. Select "File" from the menubar to display the File-menu. 
15. Select "Exit" from the File-menu to return to the Windows 98 desktop. 


Below is a list of web-based documentation that may be useful. 


1. The Academic Computing Services Computing Lab Home a at 
www.niu.edu/acs/labhome.html . 


2. The ITS Helpdesk Home Page at www.niu.edu/helpdesk . 


3. Your First Logon Session and Activating Student E-Mail at 
www.niu.edu/acs/stud-email98.html . 


Activating Your Electronic MauBox 


All registered students are provided an electronic mailbox on the student post offices 
(students.niu.edu), but you must activate the mailbox when you first arrive on campus (and after 

* you return to campus after not being registered for the previous fall or spring semester) before it 
can be used. Your post office receives messages for you and allows you to send messages. 








Eudora Pro or Netscape Messenger software found under "General Applications" - "Internet" are 
used to read and write your messages once you have activated your mailbox. 


You should also plan to regularly dispose of unwanted messages in your mailbox. The student 
mailboxes have a limited capacity, depending upon the available space in your file server storage 
space (on drive "F:"). Full mailboxes reject all messages without giving you a chance to evaluate 
their importance or notifying the sender. 


Using your Electronic Mail account in the computer labs requires that your Electronic Mail 
account be activated. 


Activating your Electronic Mail Account 

The following steps will activate your Electronic Mail Account. This must be done from the 
Computer Labs or while connected to the University via a Dial-In or One-Meg-Modem 
connection (1.e., it cannot be done from a computer that is not connected to the University). 
These steps assume that you are activating your account from on of the Computer Labs. If you 
are using a computer connected to the University in some other way, direct your web-browser to 


www.niu.edu/acs/stud-email98.htm] and follow the directions outlined there. 


1. Select the "Start" button in the lower left corner of the Windows 98 desktop to display the 
Start-menu. 


2. Select "General Applications" from the Start-menu. 

3. Select "Internet" from the submenu. 

4. Select "Activate Your Electronic Mailbox" to start the activation process. 

5. Read the material presented on screen by the Netscape Navigator browser. 

6. Click on the arrows on the right side of the page to move through the material. 

7. Double-click on the blue highlighted items to get additional information. 

8. Type in your student number (social security number) and LogonID where requested. 


9. Check the box to indicate that you understand your responsibilities in the use of these 
facilities. 


10.Check the box that indicates that information that identifies you as a student at NIU can be 
made public. Changing your status requires a letter to the Office of Registration and Records. 


11. Select "Activate Your Electronic Mailbox" when you accept all the requirements stated on 
screen. 











12. Select "Continue" in the "Security Information" dialog box. A new page indicating that "The 
Following Was Returned Based On Your Input:" with your information 1s displayed. 


13. Click on the arrows on the right side of the page to move through the page. 


14. Select "Sign Me Up" if the information is correct. If the information is incorrect, contact 
Registration and Records to confirm the University has the correct information on file for you. 


15. Select "Continue" in the "Security Information" dialog box. A new page with your Electronic 
Mail Address and Alias is displayed. 


16. Select "Print" from the File-menu to print this page of information. 
17. Select "OK" on the Print dialog box and go to the printer to pick up your output. 
18. Select "Exit" from the File-menu to return to the Windows 98 desktop. 


19. Once you have activated your e-mail, your account will be ready to use at the start of the next 
business day. 





90. Be sure to " Close Your Current Session " as described below before you leave. 


Changing Your Course Directories 


Selecting a course arranges a set of shortcuts (G:, H:, ...) pointing to section, instructor, and 
department directories for the course. The default association ("General Applications") does not 
have any section, instructor, or department directories associated with it. A shortcut to your 
home directory (F:) on the file server is always present. 


1. Select the "Start" button from the lower left corner of the Windows 98 desktop to display the 
Start-menu. 


2. Select "User Utilities" from the Start-menu. 

3. Select "Course Mapper utility" from the submenu. 

4. A dialog box with instructions to "Choose a course group to share files with" is displayed. 
There is a list in the dialog box that contains any computer-use classes for which you are 


currently enrolled. 


5. Select one of these courses by highlighting the item with the cursor, and then select "OK" or 
press Enter. The Windows 98 desktop 1s displayed. 








Formatting a Diskette 
The following procedure describes how to format a diskette using Windows 98: 
1. Insert a 1.4MB diskette in drive A:. 
a Double-click on the "My Computer" icon on the Windows 98 desktop. 
3. Select the "3 1/2 Floppy (A:)" icon in the "My Computer" window. 
4. Select "Format" from the "File"-menu to display a "Format" dialog box. 
5. Type your last name in the "Label: " box to identify the diskette if lost. 


6. Select "Start" to begin formatting the diskette. A "Format Results" dialog box is displayed on 
completion. 


7. Select "Close" on the "Format Results" dialog box. 
8. Select "Close" on the "Format" dialog box. 


9. Select the "X" in the upper right corner of the "My Computer" window to close the window. 


Closing Your Current Session 


Before leaving the lab, closing your session (logging off), or powering off the personal computer 
in a lab, make sure any personal data that you want to keep which 1s on the personal computer 
disk drive or on the network home directory (F:) is copied to a diskette. 


The personal data on the file server is not backed up, and any hard drives are erased of all 
personal data files every time the machine is powered off. 


Be sure to log off. If you don't close your session and don't turn off the computer, anyone can use 
your LogonID and examine or destroy your files. However, do not simply turn the computer off 
without logging off. Doing so may cause applications (such as Eudora Pro) to consider you as 
still being logged in and not allow you to access your files from another computer. Also, NDS 
may not consider you as logged out which would prevent you from being able to access the 
servers again for up to an hour. 


When you have finished your session, always follow the steps below to close your session. 
1. Select the "X" in the upper right corner of each window to close all the windows on screen 


when you are finished. If the window is for an application, be sure to save any data before 
closing the window. 








2. When all windows on the desktop are closed, check to make sure that there are no minimized 
applications. Minimized applications do not appear on the desktop, but do appear on the 
Start-bar (the bar at the bottom of the screen) between the Start-button and the System-tray (the 
set of icons in the lower-right corner of the screen near the clock). If you do have any minimized 
windows, click on them in the Start-bar to bring them back to the desktop. At this point, follow 
the step above to close them. 


3. Double-click on the "Logout" icon along the left side of the screen. Unlike Windows 98 
computers that you may use outside of the computer labs, the "Shutdown" item in the Start-menu 
has been inactivated because it does not effect a complete shutdown in the lab environment. 


4. Select "Logout and Restart Computer" from the "Logout and Restart Option" dialog box to 
prepare the computer for the next user. 
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ACCESSING OTHER SYSTEMS ON THE NETWORK 


The personal computers in the student computer labs are connected on a communications network and have access to 
general access file servers, to the Computer Science student file server, and to printers. In addition to the file servers, 
other systems are available through the network. MVS jobs can be submitted to and retrieved from the MVS using 
MVSBATCH and FTP. The student electronic post offices (Rice, Oats, and Wheat) and the Computer Science Sun 
SPARC 1000 provide interactive Unix sessions through Telnet and interactive file transfer through FTP. MVS is 
automatically available to students in courses whose assignments use these systems. Unix ts available to all Computer 
Science students; consult your instructor on how to activate your access. The electronic post offices are available to any 
students who have activated for electronic mail. 


CONNECTING TO UNIX OR MVS WITH FTP 


L. Select the “Start” button in the lower left corner of the Windows 95 desktop to display a menu. 

Z. Select “General Applications” to display another menu. 

3. Select “Communications” to display yet another menu. 

4. Select “FTP” to start the file transfer application. You will see several messages and finally a "Remote User 


Name:" prompt. 
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5. Type your LogonID. A "Remote Password:" prompt is displayed. 


When you mistype your LogonID, you will see several error messages and finally an “ftp>” 
prompt. 


Type user to get another “Remote User Name” prompt. 
6. Type your password. Your password is not displayed when you type it. A "ftp>" prompt is displayed. 


When you mistype your password, you will see several error messages and finally an “ftp>” 
prompt. 


Type user to get another “Remote User Name” prompt. 


You now have an open connection with the FTP server. Please note that your connection to the MVS FTP server is 
automatically closed if it is inactive for more than 5 minutes. 


7 Type he1p to list the commands available in FTP. 

8. Type help commandname to list a description of a particular command. 

9. At this point, you can do your work as described below. 

10. Type quit at the "ftp>" prompt to close your session when you have completed your work with the MVS 


FTP server and to return to the Windows 95 desktop. 


SUBMITTING JOBS TO MVS 
i; Create your source file with your editor and add the JCL statements listed in other documentation or by your 
instructor. 
Z. Place MSGCLASS=U on the JOB card in your source file, otherwise the job will not be held in the JES queue. 
3. Open a connection with the MVS FTP server if one is not already available. 
4. Type quote site filetype=jes to alert MVS to place incoming files into the JES queue. 
= Type lls or ldir to list the files on your local system (the system where you started FTP). 
6. Type lcd directoryname to change the current directory on your local system if you need to. 
7. Type put a: filename to submit your job from the diskette in the personal computer A: drive. A message 


indicating the number of bytes transmitted and how long it took is displayed when the file is received. 
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DISPLAYING MVS JOB STATUS 
L Open a connection with the MVS FTP server if one is not already available. 


2 Type quote site filetype=jes, if you have not already done so, to alert MVS to examine files in the 
JES queue. 


2: Type dir to display the status of all your jobs with all the spool files a job has associated with it. 


ftp>dir 

200 Port request OK. 

125 List started OK. 

Z951234A JOB00001 INPUT 

Z951234A JOB00002 HELD 

Z951234A JOB00003 ACTIVE 

Z951234A JOB00004 OUTPUT 3 spool Files 
250 List completed sucessfully 


ftp> 


The strings that follow your LogonID in this list are your JOBIDs. 


RETRIEVING JOB OUTPUT FROM MVS 


L. Open a connection with the MVS FTP server if one is not already available. 

2. Type quote site filetype=jes, if you have not already done so, to alert MVS to take files from the 
JES queue. 

a; Type get JOBID.X a: to download all the spool files associated with a job into a file on your diskette. 


A new filename can be added after the "a:" if you would like the file to appear with a different filename on 
your diskette. The filename is optional, but without a drive letter (A:), the files are put in volatile Swap space 


(S:). 


get JOBO0004.X a: retrieves all spool files from JOB00004 and puts them 
all in a file named JOB00004 on your diskette 


get JOBO0004.X a:progl.out retrieves all spool files from JOB00004 and puts them 
all in a file named prog].out on your diskette 


A message indicating the number of bytes transmitted and how long it took is displayed when the file is 
received. 
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DELETING A JOB ON MVS 
i, Open a connection with the MVS FTP server if one is not already available. 
Zi Type quote site filetype=jes, if you have not already done so, to alert MVS to delete spool files 
from the JES queue. 
s Type delete JOBIDto delete a job. 





TRANSFERRING FILES BETWEEN A LAB COMPUTER AND UNIX OR MVS 


Files can be transferred between an NIU host and a personal computer in the labs in either direction by running FTP 
on the personal computer. 








I. Open a connection with the MVS FTP server if one is not already available. 


Zz For MVS, type quote site filetype=file, if you have not already done so, to alert MVS (not Unix) 
to place incoming files on disk. 


3; Type put a: filename to send a file from your diskette to Unix or MVS. A new filename can be added 
to the end of this command if you would like the file to appear with a different filename in Unix or MVS. A 
message indicating the number of bytes transmitted and how long it took is displayed when the file is received. 


a Type 1s or dir to list the files under your current directory on Unix or under MVS. 

5. Type cd directoryname to change the current directory in Unix. 

6. Type lls a: or ldir a: to list the files on the diskette in the personal computer A: drive. 

fe Type lcd directoryname to change the current local directory on your personal computer. 

8. Type get filename a: to retrieve a file from your current directory on Unix or from MVS to the diskette 


in the personal computer A: drive. A new filename can be added after the "a:" if you would like the file to 
appear with a different filename on your diskette. A message indicating the number of bytes transmitted and 
how long it took is displayed when the file is received. 
ACCESSING UNIX FROM A LAB COMPUTER 
You establish a connection to a Unix system from the labs by running the Telnet communication program on a personal 
computer. Telnet on the personal computer emulates a terminal by passing most typed characters through to Unix over 
the network. The Telnet application is available from within Windows 95. To run Telnet and access a Unix system from 
Windows 95: 
i. Select the “Start” button in the lower left corner of the Windows 95 desktop to display a menu. 


Z,, Select “General Applications” to display another menu. 
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Select “Communications” to display yet another menu. 
Select “Telnet” to start the network terminal application. Unix is available once you see the "login:” prompt. 
Type your LogonID. Unix displays the "Password:" prompt. 


Type your Unix password. Your password is not displayed when you type it. When you have correctly typed 
the LogonID and Unix password associated with your LogonID, a shell prompt is displayed. 


When you mistype the LogonID or Unix password associated with your LogonID on Unix, the 
"login:" prompt is redisplayed. 


Repeat the procedure in this section beginning with Step 4. 


If this is your first time accessing Unix or if you want to change your password, see "Changing Your 
Password on Unix". 


Proceed to use Unix as instructed. Additional instructions are available from your instructor and from texts on 
Unix. 


Note that your CSCI Unix password is maintained separately from your student file server, electronic mail, and MVS 
password and that these passwords may differ unless you have made them identical. 


EXITING UNIX FROM A LAB COMPUTER 


Type Logout at the Unix shell prompt. The Windows 95 desktop is displayed. 


CHANGING YOUR PASSWORD ON UNIX 


If at any time you wish to change your password on the Unix system, perform the following steps: 


1. 


Type passwd at the Unix shell prompt. The system requests that you authenticate yourself again before it will 
accept a new password. 


passwd: Changing password for z951234 
Enter login(NIS+) password: 


Type your current Unix password. Your password is not displayed when you type it. The following message 
is displayed: 


New password: 


Type your new Unix password. Your password is not displayed when you type it. The following message is 
displayed for verification: 


Re-enter new password: 
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4. Type your new Unix password again. Your password is not displayed when you type it. 


When the two entries match, your password on Unix is changed, following message is displayed, and 
the shell prompt is redisplayed. 


NIS+ password information changed for z951234 
NIS+ credential information changed for z951234 


When the two entries do not match, the following message is displayed: 


They don’t match; try again. 
New password: 


Repeat the procedure in this section beginning with Step 2. If you want to quit at this point, hold 
down the Ctrl key and press d. 


Note that your CSCI Unix password is maintained separately from your student file server, electronic mail, and MVS 
password and that these passwords may differ unless you have made them identical. 


admin\csci\mvs ftp 19-Dec-00 
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OVERVIEW 


Both MVS and Unix systems are accessible using a remote personal computer to dial in through either the modems at 
NIU at 815.753.6600 or the modems of a local Internet Service Provider at which you have an LogonID. Direct 
connections require using PPP software to dial into a modem. The modems provide access to telecommunications 
servers (Tservers), the Internet, and NIU systems running MVS or Unix. In addition to PPP, the direct connection 
requires the use of TCP/IP, Telnet, and FTP software on the remote computer. You can also use electronic mail and 
web browser software on a direct connection. 


Submitting jobs to MVS from a remote computer requires FTP software to transfer files back and forth. The procedure 
for submitting jobs to MVS using FTP is identical whether you are using it on your personal computer, on the Computer 
Science Sun SPARC 1000, or on another remote system. 


ACCESSING MVS AND UNIX FROM A REMOTE PERSONAL COMPUTER 
USING A LOCAL INTERNET SERVICE PROVIDER 


Dialing in to campus may be a long distance call which is doubly expensive because phone connections are slow. You 
might consider looking for an Internet service provider in your neighborhood who can provide the same access that you 
receive dialing into the NIU telecommunications server from DeKalb. A search of the web can turn up a current list of 
Internet service providers in the Chicago area. 


For a fee, this service should provide a local number to dial into for Internet access. You should be able to use Telnet 
and FTP on their systems as described above to get to MVS and Unix. You may also be able to get software for your 
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PC from the service provider or from various books about the Internet that come with software. The software should 
include PPP and TCP/IP to make it possible to use Telnet, FTP, and other Internet applications from your home 
computer. Web browsers typically have a very serviceable FTP component. The books and often the service provider 
carry shareware versions that you must eventually pay for. These books are available in the campus bookstores and at 
larger bookstores in the Chicago area. 


IDENTIFYING YOUR LOGONID 
A unique LogonID (Z-ID) is created for you when you first register for classes at NIU and is used to identify you as a 


computer user from then on. Various access priviledges are attached to your LogonID each semester for which you 
register. You can obtain your LogonID at any time that you are registered with a simple phone call. 


l. Call 815.753.8995 from a Touchtone phone. 

2. Enter your student number (social security number) using the keypad. 
S: Enter your T.R.A.C.S. registration PIN using the keypad. 

4... Select the LogonID option. 


SETTING UP A DIRECT CONNECTION FROM A REMOTE PERSONAL COMPUTER 


To dial-in to the Internet you must install and configure the communications software on your computer. This software 
may be part of your operating system in which case you simply need to configure it. 


1. Install TCP/IP, PPP, FTP, Telnet, and any other Internet software on your personal computer following the 
instructions supplied with the software. 
ox Configure the TCP/IP software so that the NIU Tserver dynamically provides the IP address for your 
connection using the following information: 
IP address: Leave blank or set to 0.0.0.0. 
Hostname: your logonid.home 
Netmask: 290.200-250.0 
Nameserver: 131.156.1.11 
Domainname: niu.edu 
3. Configure your PPP dialer to use PAP/CHAP authentication using the following information: 
PPP login: your logonid 
PPP password: your password 
Dial to: 1.815.753.6600 when calling DeKalb 
Dial to: 1.847.645.3050 when calling Hoffmann Estates 
Dial to: 1.815.332.4903 when calling Rockford 
Dial to: 1.630.990.0541 when calling Oakbrook 


Students have a single, common password for dial-in, MVS, the file and print servers in the labs, and their electronic 
mailbox. There is an independent (different) password for access to the Computer Science Unix systems. 


4. Use PPP to dial the NIU Tserver with your modem. 
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=o Start FTP, Telnet, or any other communications software it will use the Internet connection that you have set 
up with TCP/IP and PPP. 


Any of the Internet applications, for instance FTP, can now be run and do work in the same manner as if the user were 
connected to the campus network (although they will be somewhat slower). 


Be sure to close your PPP session when not in use to avoid unnecessary phone charges. 


CONNECTING TO MVS WITH FTP 


I: Start your FTP software package (the FTP client). The way you do this may vary depending on the 
software package, for instance, if you are working from a Unix system, type ftp. An “ftp>” prompt is 
displayed. 

2 Type open mvs.cso.niu.edu to open an FTP session with MVS. A connection to MVS results in a 


"Name (mvs.cso.niu.edu):" prompt. 
a, Type your LogonID. A "Password:" prompt is displayed. 


When you mistype your LogonID, you will see several error messages and finally a “ftp>” 
prompt. | 


Type user to get another "Name (mvs.cso.niu.edu):" prompt. 


4. Type your password. Your password is not displayed when you type it. A "ftp>" prompt is displayed. 





When you mistype your password, you will see several error messages and finally a “ftp>”’ 
prompt. 








Type user to get another "Name (mvs.cso.niu.edu):" prompt. 


You now have an open connection with the FTP server. Please note that your connection to the 
MVS FTP server is automatically closed if it is inactive for more than 5 minutes. 


3. Type help to list the commands available in FTP. 


6. Type help commandname to list a description of a particular command. 
At this point, you can do your work as described below. 
Ts Type close at the "ftp>" prompt to close your connection with the MVS FTP server. 


Be sure to close your connection when you are not transferring files, for instance when you are editing your files in 
another window. Remember that you are sharing a limited number of FTP connections. 


8. Return to Step 2 above to reconnect. 
9. Type quit at the "ftp>" prompt to close your session when you have completed your work with the MVS 
FTP server. 
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SUBMITTING JOBS TO MVS 


Create your source file with your editor and add the JCL statements listed in other documentation or by your 
instructor. 


Place MSGCLASS=U on the JOB card in your source file, otherwise the job will be held in the JES queue. 
Open a connection with the MVS FTP server if one is not already available. 

Type quote site filetype=jes to alert MVS to place incoming files into the JES queue. 

Type 11s or ldir to list the files on your local system (the system where you started FTP). 

Type lcd directoryname to change the current directory on your local system if you need to. 


Type put a: filename to submit your job from your diskette to MVS. A message indicating the number 
of bytes transmitted and how long it took is displayed when the file is received. 


DISPLAYING MVS JOB STATUS 
Open a connection with the MVS FTP server if one is not already available. 


Type quote site filetype=jes, if you have not already done so, to alert MVS to examine files in 
the JES queue. 


Type dir to display the status of all your jobs with all the spool files a job has associated with it. 


ftp>dir 

00 Port request OK. 

25 List started OK. 

Z951234A JOB00001 INPUT 

Z951234A JOB00002 HELD 

Z951234A JOB00003 ACTIVE 

Z951234A JOB00004 OUTPUT 3 spool Files 
50 List completed successfully 


ftp> 


The strings that follow your LogonID in this list are your JOBIDs. 





RETRIEVING JOB OUTPUT FROM MVS 
Open a connection with the MVS FTP server if one is not already available. 


Type quote site filetype=jes, if you have not already done so, to alert MVS to take files from the 
JES queue. 
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3. 


Type get JOBID.X a: to download all the spool files associated with a job into a file on your diskette. 
A new filename can be added after the "a:" if you would like the file to appear with a different filename on 
your diskette. 


get JOBOO0004.X a: retrieves all spool files from JOB00004 and puts them 
all in a file named “JOB00004” on your diskette 


get JOBO0004.X a:progl.out retrieves all spool files from JOB00004 and puts them 
all in a file named “progl.out” on your diskette 


A message indicating the number of bytes transmitted and how long it took is displayed when the file is received. 


DELETING A JOB ON MVS 
Open a connection with the MVS FTP server if one is not already available. 


Type quote site filetype=jes, if you have not already done so, to alert MVS to delete spool files 
from the JES queue. 


Type delete UJOBID to delete a job. 


TRANSFERRING FILES BETWEEN A REMOTE PERSONAL COMPUTER AND UNIX OR MVS 


Files can be transferred between a remote personal computer and Unix or MVS in either direction without 
submitting the file for processing. 


Li 


Z. 


Open a connection with the MVS FTP server if one is not already available. 


Type quote site filetype=file, if you have not already done so, to alert MVS (not Unix) to 
place incoming files on disk. 


Type put a: filename to send a file from your diskette to Unix or MVS. A new filename can be added 
to the end of this command if you would like the file to appear with a different filename in Unix or MVS. 
A message indicating the number of bytes transmitted and how long it took is displayed when the file is 
received. 

Type 1s or dir to list the files under your home directory on Unix or MVS. 

Type cd directoryname to change the current directory in Unix or MVS. 

Type lls a: or ldir a: to list the files on the diskette in the personal computer A: drive. 

Type lcd directoryname to change the current local directory on your personal computer. 

Type get filename a: to retrieve a file from your current directory on Unix or from MVS to the 
diskette in the personal computer A: drive. A new filename can be added after the "a:" if you would like 


the file to appear with a different filename on your diskette. A message indicating the number of bytes 
transmitted and how long it took is displayed when the file is received. 
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ACCESSING UNIX 


You establish a connection to a Unix system from the labs by running the Telnet communication program on a personal 
computer. Telnet on the personal computer emulates a terminal by passing most typed characters through to Unix over 
the network. 


1. 


tO 


Start your Telnet software package (the Telnet client). The way you do this may vary depending on the 
software package. A “telnet>” prompt is displayed. 


Type open mp.cs.niu. edu to conect to the Computer Science Unix system. Unix is available once you 
see the "login:" prompt. 


Type your LogonID. Unix displays the "Password:" prompt. 
Type your Unix password. Your password is not displayed when you type it. 


When you have correctly typed the LogonID and Unix password associated with your LogonID, a 
shell prompt is displayed. 


When you mistype the LogonID or Unix password associated with your LogonID on Unix, the 
"login:" prompt is redisplayed. 


Repeat the procedure in this section beginning with Step 3. 


If this is your first time accessing Unix or if you want to change your Unix password, see “Changing 
Your Password on Unix". 


Proceed to use Unix as instructed. Additional instructions are available from your instructor and from texts on 
Unix. 


EXITING UNIX 


Type logout at the Unix shell prompt. 


CHANGING YOUR PASSWORD ON UNIX 


If at any time you wish to change your password on the Unix system, perform the following steps: 


i 





Type passwd at the Unix shell prompt. The system requests that you authenticate yourself again before it will 
accept a new password. | 


passwd: Changing password for z951234 
Enter login(NIS+) password: 


Type your current Unix password. Your password is not displayed when you type it. The following message 
is displayed: 


New password: 
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2, Type your new Unix password. Your password is not displayed when you type it. The following message is 
displayed: 


Re-enter new password: 
4. Type your new Unix password again. Your password is not displayed when you type it. 


When the two entries match, your password on Unix is changed, following message is displayed, and 
the shell prompt is redisplayed. 


NIS+ password information changed for z951234 
NIS+ credential information changed for z951234 


When the two entries do not match, the following message is displayed: 


They don’t match; try again. 
New password: 


Repeat the procedure in this section beginning with Step 2. If you want to quit at this point, hold 
down the Ctrl key and press d. 


Note that your CSCI Unix password is maintained separately from your student file server, electronic mail, and MVS 


password and that these passwords may differ unless you have made them identical. 


admin\csci\csciremo 19-Dec-00 
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PREFACE 


This book has been designed to take you on a tutorial trip through the process of creating and 
submitting a program to the mainframe using the MVSBATCH facility. This book covers the basics 
necessary for creating a program file, editing existing program files, submitting program files as 
mainframe jobs, fetching executed jobs, managing programs and fetched jobs, and using predefined 
utilities for additional mainframe file management. This manual has been designed for you to take 
to the lab and self-learn the system. After the initial session, you can use this manual for future 
reference. 


LOG ON PROCEDURES 


TURN ON THE COMPUTER 


If not already on, the computer and monitor 
must be turned on. Usually the switch on the 
monitor is on the right side near the top. The 
switch to turn on the computer is usually on the 
front of the CPU (central processing unit) on 
the right side. Flip this switch up to turn on the 
machine. The machine will go through a series 
of steps to attach to the network server and then 
ask you a sequence of questions to complete 
the log on process. NOTE: Depending upon 
the machine that you are working with, the 
on/off switches may be in a different location 
than the one stated above. If you have trouble 
locating the on/off switches on either the 
monitor or CPU, ask the lab attendant for help. 





LOG ON PROCEDURES 


Log on procedures are outlined in the Using the Computer Science Student Computer Facilities. 
Refer to this document and any instructions provided by your instructor. The log on process is a two 
step process. First you must log on to the network and second you must provide information that 
allows the MVSBATCH facility to log into MVS when needed. Providing this information does 
not mean that you are actually logged in to MVS. This manual will now illustrate the screen 
sequence that you will see. The screen examples found here are the ones which require user 
responses. Intermediate screens have been excluded. 


1. LOG ONTO THE NETWORK AND RUN MVSBATCH 


Refer to the Using the Computer Science Student Computer Facilities document for the correct 
procedures for logging into NIU's computer network and choosing the appropriate operating system 





and class application set. 


Once you have chosen your class application set, you may run MVSBatch. Use one of the 
following instruction sets to run MVSBatch 


A. To run MVSBatch from the CSL Main Menu under Dos, 
1. From the main screen, select 
F. Connect to NIU Host. 


Use the ARROW keys to move the color bar to highlight selection 'F" and press ENTER or 
type the letter 'F" and press ENTER. 


2. At the next screen, select 
A. MVSBATCH 


Use the ARROW keys to move the color bar to highlight selection 'A' and press ENTER or 
type the letter 'A' and press ENTER. 


B. Torun MVSBatch from Windows, 
1. Click on the DOS Applications Group Icon. 


2. Click on the MVSBATCH Icon. 


C. Torun MVSBatch from Windows 95, 
1. Click on the Program Group Icon. 


2. Click on the MVSBATCH Icon. 


STEP 2: PROVIDING MVS LOGIN INFORMATION TO MVSBATCH 


At this point you will see the MVSBATCH Welcome screen. The purpose of this screen is to gather 
user information required to log into MVS to submit programs or fetch output. When you have 
provide the requested information, MVSBATCH will attempt to momentarily log into MVS to 
confirm the accuracy of the information provided. However, during most your MVSBATCH 














session, you are NOT actually logged into MVS. Also, remember that MVS is a different system 
than the network and you must change your initial password on MVS even if you have already 
changed your network password.. 


Welcome to the MVS Batch Facility 


Please enter your MVS logonid and password, and work directory 
(Your password will not display when typed). 


Logonid: 
Password none 


LOGONID NUMBERS: 


At the Logonid prompt, type in the Z9????? number that was assigned to you. This is the same 
logonid number that was used to log on to the network. Once you have typed in your logonid 
number, press the TAB key to bring the cursor down to the password prompt. 


PASSWORDS: 


The password has initially been set to the last six (6) digits of your social security number. It can 
be changed later via a menu selection. 


NOTE: You are now providing information required to log on to another system called MVS. 
Even though you changed your password when you logged on the network, it has not been 
changed on MVS. You must use the last six digits of your social security number as your 
password the first time that you run MVSBatch. 


At the password prompt type in the last six digits of your social security number. Press ENTER. 
(NOTE: When the password is typed, it will not show up on the screen. This is for security reasons. 
Type your password carefully). MVSBatch will require you to change your password at this point. 











WORK DIRECTORY: 


Each user has been given storage space on the file server on the f: drive. You will notice that the 
location of this storage is specified on the screen. This path may vary depending on which operating 
system and application set you chose during your network login. 


You are permitted to change this and might want to save your files to a different subdirectory or on 
your own 3.5 inch disk. This way you can keep a copy of your files and edit the files on a computer 
at another location. Changing you directory is described later.. 


Additionally, facilities for managing files on 3.5 inch diskettes are available on each operating 
system. 


HOW IT WILL LOOK: 


The following is an example of how the log on screen will look. 


Welcome to the MVS Batch Facility 


Please enter your MVS logonid and password, and work directory. 
(Your password will not display when typed). 


Logonid: LIee ee? 
Password: XXXXX 
Work directory: F:\12345\2Z29????? 


Note that the user's password will not show up on the actual MVS Batch screen. If you are running 
MVSBatch for the first time, it will insist you change your password. See the Change your MVS 
password section below for the rules and suggestions on how to select a good password.. 


MVSBATCH: 





At this point you will see the MVSBATCH main menu. It looks similar to the following: 


VEO DMDUIAUAWNHH 


MVS Batch Facility Main Menu 


Create a new JCL file 

Fdit an existing JCL file 

Submit a JCL file to MVS for fetch 

Update MVS batch job status 

Fetch the output of an MVS batch job 
Display an MVS job output file 

Submit a JCL file to MVS for print 

Purge an MVS batch job 

Delete a MVS job output file 

Miscellaneous items (macros, options, etc.) 
Display information about the MVS Batch Facility 
Exit the MVS Batch‘Facility 





We will take each selection one by one and explore its function. To make a selection simply type 


the number or letter of the required function. You may also use the ARROW keys to move the white 
bar to highlight the desired selection. 


The first time that you select MVSBATCH you will want to change your password on MVS. I 
suggest that you change it to the same password that you will be using on the network. This will 
save confusion at a later date. To change your password, select 'M': 


M. Miscellaneous items (macros, options, etc.) 


This selection displays the Miscellaneous items menu. Now select '4.' : 


4. Change your personal options 


This selection displays the Change MVS Batch Facility options menu. Now select '1.' 








1. Change your MVS password 


Selection | allows you to change your password for MVS to a new password that is between 
>» and 8 characters long and is comprised of a combination of numbers and letters. Make it 
something that is easy to remember but not obvious. For example, do not make it your 
name, birth date or anything else that can be easily identified with you as the logonid owner. 
It is often advantageous to set this password to the same password that was used to access 
the student lab network. This way you will not get confused between which password 
belongs to the network and which password belongs to MVS. It is easier to remember when 
both passwords are the same! The first time that you log on MVS your password is the first 
five digits of your social security number. You want to change this. The first time that you 
log on MVS and change your password you may encounter some error messages during this 
process. Do not become alarmed by this and just ignore the error messages. When you log 
on to MVS for the second time use the new password, if you have problems with this ask for 
help. 


After changing your password the first time you select MVSBATCH, you must get back to the main 
menu to continue with the tutorial. Pressing the ESC key will take you back one menu. Press the 
ESC key to work your way back to the main menu. 


Now that you are back to the main menu, we will take each selection one by one and explore its 
function. 








1. Create a new JCL file 


When you want to type a new file, from the main MVSBatch menu, select 1. This will show you 


the following screen: 
Create a new JCL file 


Please enter the name of your new JCL file. (Press F5 to list the 
files in your work directory. ) 


File name: 


You will type in the name of the file that you want to create. The file name must consist of a name 
which must be between 1 and 8 characters long, then a period, and then a three character extension. 
The system is set up so that the extension must start with the letters JC, the third letter can be of your 
choosing, ie: JCL. 


After specifying the name, the editor VEDIT will be invoked. Using this editor you will type in your 
file. We will discuss the editing process in a later section of this manual. 


After ending the edit session, if you are not already at the MVS Batch main menu, press ESC to 
return to the MVS Batch main menu. 


2. Edit an existing JCL file 


When you already have existing files that you have been working on and you want to edit one of 
those files, take selection 2. This should bring up a list of the files names with the extension JC? that 
are located in your work directory. Use the ARROW keys to highlight the name of the file that you 
want to edit. Then press ENTER. This will take you into the editor so that you can continue 
working on this particular file. 


Edit an existing JCL file 





Please select a file name to edit: 


MVSBAT.JCL ES Lia Cle 





3. Submit a job file to MVS for fetch 


Once a file has been created and the source code is ready to be tested, you must submit the file to 
MVS for execution. Take selection 3. This will check the work directory for all of the files with the 
proper extension. Use the ARROW keys to highlight the file that you want to execute. Press 


ENTER. 
Submit a JCL file to MVS for fetch 


Please select the JCL file to submit to MVS: 





MVSBAT .JCL aol Cl 


After the file has been selected and submitted, the system will return to the main MVSBatch screen. 
Notice, however, that the MVS jobs listing has changed. Each file that is submitted is called a job. 
Each job, when submitted, has a number. The MVS jobs category will tell you the status of all of 
your jobs. For example if several jobs have been submitted you might see: 


Current jobs: O893w, 4698w and 62531 (w=work dir only; 
1=awaiting execution) 


Work directory: F:\12345\292????? (8M bytes free) 





The '1' after the job number means that the job is waiting its turn to execute. The 'w' means that a 
copy of the output from the job is located in the work directory. The work directory can be located 
on the file server or ona floppy disk. The default is on the file server; however, you may change this 
through a menu selection located under the main menu selection "Miscellaneous items", "Change 
MVS Batch Facility options", "Change MVSBATCH values." 
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After submitting the required files, if you are not already at the MVS Batch main menu press ESC 
to return to the main menu. 


4. Update MVS batch job status. 


This selection simply checks the current status of all of your jobs and updates the MVS jobs category 
at the bottom of the screen. For example: 


Current jobs: 0893w, 4698w and 6253u(u=unfetched, 
w=work dir only) 


Work directory: F:\12345\29????% (8M bytes free) 





Notice that job number 6253 now 1s followed by a'u'. In the last example it was followed by an'i'. 
The 'u' means that the job has finished executing and 1s waiting for you to retrieve or fetch the output 
from MVS and store it in your work directory. 


5. Fetch the output of an MVS batch job 


In order to be able to look at the output of the jobs which you have submitted to MVS, you must 
retrieve, or fetch, the output. When this selection is taken you will see a screen similar to the 


following: 
Fetch the output of an MVS batch job 


Please select an MVS job to fetch 








6253 Job 29?????; awaiting fetch 





Use the ARROW keys to highlight the job number that you want. Press ENTER. If you wish you 
may select more than one job at a time. Highlight each job number that you want by pressing the 


1] 





SPACE BAR. When all job numbers have been selected, press ENTER. 
If you are not already at the MVS Batch main menu press ESC to return to the main menu. 


Fetching a job places a file in the work directory under the job number with an extension of X. For 
example, the output for job number 6253 would be in the file J6253.X in the work directory. 


Current jobs: O0893w, 4698w, and 6253w (w=work dir only) 


Work directory F:\12345\z9????? (8M bytes free) 





When you return to the main menu notice that the status of job 6253 in the current job category has 
changed. 


6. Display MVS job output file 


This menu selection is used to view the output of a fetched job. The system will list all of the job 
files in the work directory. 


Display MVS job output file 


Please select a fetched output file to display 
Select the job number of the job output file to display: 
0893 Job 297???? (1996/07/17; 17:01:12); not on MVS 


4698 Job Z9????? (1996/07/20; 09:43:23); not on MVS 
6253 Job 29????? (1996/08/01; 23:59:59); not on MVS 





Use the ARROW keys to select the job number of the output that you would like to look at. Press 
ENTER. 
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A special type of viewer called a browser allows you to look at the contents of the output file. You 
may notice that the lines in the output are too long to fit on the screen. Use the RIGHT or LEFT 
ARROW keys to move the screen to the right or left in order to see an entire line. 


The PAGE UP and PAGE DOWN keys will scroll the output on the screen up or down an entire 
screen ata time. The UP and DOWN ARROW keys will scroll the screen up or down one line at 
a time. 


For more explicit instructions about using the browser press F1 for help. 


Press F10 to exit the browser and go back to the job selection screen. From here, if you are not 
already at the MVS Batch main menu, press ESC to return to the main menu. 


7. Submit a JCL file to MVS for print 


Once you have reached a point where you want to print the output of a file, you must submit the job 
and select a printer on which to print the program and its output. Note that this does not have to be 
the printer that you selected when you logged on the student network. The first part of this operation 
is very Similar to when you simply submitted a job for execution and then fetched the output in order 
to look at it using the browser. This time you will select a file to execute but the output will not 
come back to the fetch queue, instead it will go to the specified printer. 


Start by using the ARROW keys to select the file that you wish to execute. Press ENTER. 


Submit a JCL file to MVS for print 


Please select the JCL file you wish to submit to MVS: 


MVSBAT .JCL TEST1 .JCL 





You will then see a screen similar to the following where you will use the ARROW keys to highlight 
the correct printer. Press ENTER. 
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You have selected MVSBAT.JCL for submission to MVS for execution and 


Princ. You must now select the printer on which you wish MVS to print 
your job. 

CSL (route code RMT5) SCL (route code RMT24) 

HEEC (route code RMT14) UCL (route code RMT7) 

LOCAL | FRL (route code RMT57) 

MUC (route code RMT15) 





Once you have selected the desired print location, you are given the option of correcting the printer 
selection. 


You have asked to submit MVSBAT.JCL to MVS for print to CSL. 


| Are you sure you want to do this? yes 





At this point if you press ENTER, it will submit and print the job and then go back to the MVS 
Batch main menu. Notice that a new job number has been added to the MVS jobs category. 


If you type no, you will again end up back at the MVS Batch main menu. 


8. Purge an MVS batch job 


This selection lists all of the job numbers of jobs that are still in the fetch queue. You will want to 
keep this clear of any unnecessary jobs. Use the ARROW keys to highlight the number of the job 
that you wish to delete. Press ENTER. 


Purge an MVS batch job 
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Please select an MVS job to purge 


6253 Job 297277??; awaiting fetch 
6254 Job 2927?7????; executing 


After the job has been deleted you will end up back at the MVS Batch main menu. 


9. Delete a MVS output file 


If you leave the old output files from your jobs in the work directory you will begin to run out of 
space. Choose selection 9 to delete the output files from the work directory. 


Delete an MVS output file 


Please select a fetched output file to delete 


0893 Job Z9????? (1996/07/19; 17:01:12); not on MVS 
4698 Job Z292????? (1996/07/20; 09:43:23); not on MVS 
6253 Job 7.92?2??? (1996/08/01; 23:59:59); not on MVS 





Use the ARROW keys to highlight the job number of the output file to delete. Then press ENTER. 


If you had selected job 6253, you would then get the message: 


The output for MVS job 6253 has been deleted from your work 
directory. 


Press any key to continue: 


At this point you will return to the MVS Batch main menu. 
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M. Miscellaneous items (macros, options, etc.) 


The miscellaneous items selection brings up a sub-menu which will allow you to do a variety of 


functions. | 
Miscellaneous items 
1. List contents of your work directory 
2. Delete a file from your work directory 
3. Invoke MVS Batch Facility macro 
4. Change your personal options 
5. Display MVS Batch Facility session information 
6. Display a file in your work directory 
N. Display the latest MVS Batch Facility news 





1. List contents of your work directory 


This selection simply lists all of the files in your work directory. 


2. Delete a file from your work directory 


This selection lists all of the files in the work directory. Use the ARROW keys to highlight 
the name of the file that you wish to delete. Press ENTER. You will be prompted for a 
response to "Do you really wish to delete filename?" If you press ENTER, the file will not 
be deleted. If you type yes the file will be deleted. 


3. Invoke MVS Batch Facility macro 


There are various macros for the more experienced user that can be performed via this 
selection. These are: ACFRULES, ARCHIVE, ARCLIST, BACKLIST, COMPRESS, 
DELMEMS, MVSLIST, REMOVE, RENDSNS, RENMEMS, RESTORE and 
SHOWMEMS. 
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4. Change your personal options 


This selection brings up another menu: 


Change your personal options 


Change your MVS password 
Change file and program options 
Change MVS and FTP options 
Change colors 

Change miscellaneous options 
Restore default option settings 





DU BWDP 





The selections that we will be most concerned about are 1 and 2. 


Selection 1 allows you to change your password for MVS to a new password that is between 
5 and 8 characters long and is comprised of a combination of numbers and letters. Make it 
something that is easy to remember but not obvious. For example, do not make it your 
name, birth date or anything else that can be easily identified with you as the logonid owner. 
It is often advantageous to set this password to the same password that was used to access 
the student lab network. This way you will not get confused between which password 
belongs to the network and which password belongs to MVS. It is easier to remember when 
both passwords are the same! 


Selection 2 allows you to change the file name extension of your program files from the JC? 
requirement and change your work directory from the one that you established at the time 
that you logged on. 


Press ESC to return to the previous menu. 
5. Display MVS Batch session information 


This selection lists all of the current settings for MVS Batch. Press ESC to return to the 
previous menu. 
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? Display the latest MVS Batch Facility News 


The more experienced user might want to read this to learn more about MVS Batch and any possible 
short cuts that have not been covered in this manual. 


X. Exit the MVS Batch Facility 


Choose this selection to leave MVS Batch and return to the network menu. 
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EDITING FILES USING VEDIT 


The editor that we will be using to edit our files is called VEDIT. It is a text editor. While you are 
in the lab you will be using this editor, however, if you are working in another location, make sure 
that you save your file in text format. 


Once a new file has been opened for editing, new lines must be inserted or added in order to type 
your program. While editing, the possibility of typing errors exists and, therefore, there must also 
be a means for deleting and changing the contents of lines. 


In this section we will work with manipulating text within a file. The first portion will insert ten new 
lines. We will then demonstrate how to add, delete, copy and move lines of text. For practice, 
implement the instructions as the tutorial manual goes through the examples. In order to be able to 
do this, log on to MVS. Choose selection 1, create a new file, and name the new file 
TESTEDIT.JCL. The assumption will be made at the beginning of the MOVE and COPY 
instructions that the screen has been restored to the original ten lines of text. Use the DELETE 
instruction to remove any additional lines and the INSERT instruction to restore any missing lines. 
Make use of the ARROW keys to put the cursor in the proper location for changes. 


HELPFUL HINTS: 


1. In order to view the menu bar at the top of the screen, press F10. If you do not want the sub- 
menus to show automatically, use the RIGHT ARROW key to highlight the CONFIG title 
selection. Use the DOWN ARROW until SCREEN DISPLAY 1s highlighted. Press ENTER. 
This brings up another sub-menu. Use the DOWN ARROW until ENABLE SUB-MENU 
PREVIEW is highlighted. Press ENTER. Notice that it now says NO. Press the ESCAPE key 
until the menu bar has disappeared. 


2. The keystroke combination of CTRL and C removes all menus. 


3. Use the ARROW keys to move the cursor around the screen. 


4. Press the PAGE UP key to view the previous screen of text within the file. 


5. Press the PAGE DOWN key to view the next screen of text within the file. 
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Press the TAB key to advance to a preset tab position within each line. 


The F1 key brings up the help menu. 


There are several ways to accomplish each of the typical editing features. You can use key 
stoke combinations, the mouse, or the menu. 
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INSERTING LINES 


Whether beginning to edit a new file or adding lines to an existing file, the INSERT mode can be 
used. The INSERT mode allows an unlimited number of lines to be added to a specific location in 
a file. Press the INSERT key to toggle between the insert mode and the replacement mode. Look 
at the upper right corner of the screen. If you are in the INSERT mode it should say INS otherwise 
you are in the REPLACEMENT mode. 


NEW FILES: 


When beginning an edit session on a new file, make sure that you are in the INSERT mode and 


simply type. It will allow you to type in as many lines as required. End each line by pressing the 
ENTER key. 


EXISTING FILES: 


To add lines in previously existing text use the INSERT mode. Position the cursor on the line in the 
file which immediately follows where the new lines are to be inserted. This is done by (1) using the 
PAGE UP and PAGE DOWN keys to scroll to the proper line or (2) using the UP and DOWN 
ARROW keys to locate the desired line or (3) use the mouse to position the cursor on the appropriate 
line. Press ENTER. This creates a blank line before the current line. Move the cursor to the empty 
line and begin typing the additional lines of text. 


TRY IT! 


Type the following ten lines in the file TESTEDIT.JCL. 


THIS IS LINE 
THIS IS LINE 
THIS IS LINE 
THIS IS LINE 


= 
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DELETING LINES 


There are two ways to delete lines of text. One is to do a block delete and the other is to delete a 
single line of text. 


LINE DELETE: 


To delete a line of text, place the cursor on the line that you want to delete and press the CTRL key 
and the Y keys simultaneously. This deletes the line. 


If you change your mind and do not want to delete the line that was highlighted press the CTRL and 
U keys to undo. 


BLOCK DELETE: 


It is also possible to delete more than one line at a time in this manner. Put the cursor on the first 
line to be deleted. Press CTRL and L. Notice the highlighting. Using the DOWN ARROW key 
move the cursor to the last line of the block of text to be deleted. Notice that all of the lines between 
the first and last lines have become highlighted. To delete the highlighted block press the SHIFT 
key and the DELETE key simultaneously. 


If you change your mind and do not want to delete the block that is highlighted press the CTRL and 
U keys to undo. 


Now try this in your test file. Delete lines 3, 4, 5, and 6. 


ne 





THIS 
THIS 
THIS 


THIS 
THIS 
THIS 


2 
i 
Is 


Is 
Is 
Is 


DELETE 


fi > I BS 
THIS 
fd BS 


THIS 
THIS 
gil; MS 
A td 
IHL 
pis Be 


Using SHIFT INSERT, add back the original lines three through six. You will need restore the file 
to its original contents in order to follow the next section. 


Rather than have to remember all of the appropriate keystrokes you may want to use the menu 
system to guide you through the deleting process. 


IS 
IS 
IS 


LINE 
LINE 
LINE 


LINE 
LINE 
LINE 


LINE 
LINE 
LINE 


The result should be: 


RESTORE IT! 


QO uP WHE 


lO © wsJ 


<== put cursor on this line and press CTRL L 


<== put cursor on this line then press SHIFT 


AN ALTERNATE METHOD FOR BLOCK DELETING USING THE MENU: 


Put the cursor on the first line of the block to be deleted. Press F10 to display the menu. Use the 
RIGHT ARROW key to move to the BLOCK selection. Press ENTER to bring up the sub-menu. 
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Use the DOWN ARROW key to highlight SET LINE MARKER. Press ENTER. If you still see 
the main menu, press the ESC key until the main menu disappears. 


Use the DOWN ARROW to find the end of the block that you want to delete. Press F10 to display 
the main menu. Use the LEFT ARROW key to move to the EDIT selection. Press ENTER to 
display the sub-menu. Using the DOWN ARROW highlight the CUT TO SCRATCH PAD 
selection. Press ENTER. Notice that all of the highlighted lines 1n your text have been deleted. 


USE THE MOUSE: 


You can use the mouse to highlight the block of text that you want to delete. Simply use the mouse 
to put the cursor on the first line of text to be deleted. Press the left mouse button and hold it down 
while dragging the mouse downward. Notice that the cursor will move down on the screen and 
highlight the lines that it encounters as 1t moves. 


The menu bar can be displayed by moving the cursor to the top line of the screen using the mouse. 
Click the left mouse button and the menu bar will appear. You can use the mouse to put the cursor 
on the desired menu selection and then click the left mouse button. Follow the menu directions 
given in the previous section to continue the deleting process but instead use the mouse to 
manipulate the menu instead of the ARROW keys and the ENTER key. 
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MOVING LINES 


There are two ways to move lines of text. One is to do a block move and the other is to move a 
single line of text. 


LINE MOVE: 


To move a line of text, place the cursor on the line that you want to move and press the CTRL key 
and the L key simultaneously. This marks the line. You should see the line become highlighted. 
Press the SHIFT and DELETE key simultaneously. To move the highlighted line, position the 
cursor on the line following where the highlighted line is to go and press the SHIFT key and the 
INSERT key simultaneously. 


If you change your mind and do not want to move the line that was highlighted press the CTRL and 
U keys as many times as needed to undo the move. 


BLOCK MOVE: 


It is also possible to move more than one line at a time in this manner. Put the cursor on the first line 
to be moved. Press CTRL and L. Notice the highlighting. Using the down ARROW key move the 
cursor to the last line of the block of text to be moved. Notice that all of the lines between the first 
and last lines have become highlighted. To delete the highlighted block press the SHIFT key and 
the DELETE key simultaneously. To move the previously highlighted block of lines, position the 
cursor on the line following where the block of lines is to go and press the SHIFT key and the 
INSERT key simultaneously. 








If you change your mind and do not want to move the block, press the CTRL and U keys to undo. 


NOW using the test file, move lines 3 through 7 so that they follow line 8. 
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THIS 
THIS 
THIS 


di: 
THIS 
py = 
THIS 


IS 
IS 
Is 
Is 
Is 
Is 
Is 


DELETE 
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THIS 
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The result should be: 


LINE 
LINE 
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LINE 
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LINE 
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put cursor on this line and press CTRL L 


put cursor on this line and press SHIFT 


Now move the block of lines back to its original position. 


AN ALTERNATE METHOD FOR BLOCK MOVING USING THE MENU: 


Rather than have to remember all of the appropriate keystrokes you may want to use the menu 
system to guide you through the moving process. 


26 








Put the cursor on the first line of the block to be moved. Press F10 to display the menu. Use the 
RIGHT ARROW key to move to the BLOCK selection. Press ENTER to bring up the sub-menu. 
Use the DOWN ARROW key to highlight SET LINE MARKER. Press ENTER. If you still see the 
main menu, press the ESC key until the main menu disappears. 


Use the DOWN ARROW to find the end of the block that you want to move. Press F10 to display 
the main menu. Use the LEFT ARROW key to move to the EDIT selection. Press ENTER to 
display the sub-menu. Using the DOWN ARROW highlight the CUT TO SCRATCHPAD 
selection. Press ENTER. Notice that all of the highlighted lines in your text have been deleted. | 


Now position the cursor on the line immediately following the place to insert the moved lines. Press 
F10 to display the main menu. Use the RIGHT ARROW key to move to the EDIT selection. Press 
ENTER to display the sub-menu. Using the DOWN ARROW highlight the PASTE SCRATCHPAD 
selection. Press ENTER. The previously deleted lines will now be inserted. 


USE THE MOUSE: 


You can use the mouse to highlight the block of text that you want to move. Simply use the mouse 
to put the cursor on the first line of text to be moved. Press the left mouse button and hold it down 
while dragging the mouse downward. Notice that the cursor will move down on the screen and 
highlight the lines that it encounters as 1t moves. 


The menu bar can be displayed by moving the cursor to the top line of the screen using the mouse. 
Click the left mouse button and the menu bar will appear. You can use the mouse to put the cursor 
on the desired menu selection and then click the left mouse button. Follow the menu directions 
given in the previous section to continue the moving process but instead use the mouse to manipulate 
the menu rather than the ARROW keys and the ENTER key. 
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COPYING LINES 


There are two ways to copy lines of text. One is to do a block copy and the other is to copy a single 
line of text. 


LINE COPY: 


To copy a line of text, place the cursor on the line that you want to copy and press the CTRL key and 
the L key simultaneously. This marks the line. You should see the line become highlighted. Press 
the CTRL and INSERT key simultaneously. To insert a copy of the highlighted line, position the 
cursor on the line following where the copy is to go and press the SHIFT key and the INSERT key 
simultaneously. 


If you change your mind and do not want to copy the line that was highlighted press the CTRL and 
U key to undo. 


BLOCK COPY: 


It is also possible to copy more than one line at a time in this manner. Put the cursor on the first line 
to be copied. Press CTRL and L. Notice the highlighting. Using the DOWN ARROW key move 
the cursor to the last line of the block of text to be copied. Notice that all of the lines between the 
first and last lines have become highlighted. To copy the highlighted block press the CTRL key and 
the INSERT key simultaneously. To insert a copy of the highlighted block of lines, position the 
cursor on the line following where the highlighted line is to go and press the SHIFT key and the 
INSERT key simultaneously. 


If you change your mind and do not want to insert a copy of the block that was highlighted press the 
CTRL and U keys to undo. 


NOW using the test file, copy lines 2 through 4 so that a copy of these lines follows line 6. 
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fy Se 
THIS IS 
THIS IS 
THIS IS 
INSERT 

tno: Ls 
THIS IS 
THIS IS 
INSERT 

THIS IS 


The result should be: 


THIS IS 
THIS IS 
THIS IS 
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THIS IS 
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== put cursor on this line, press CTRL L 


<== put cursor on this line, press CTRL 


<== put the cursor on this line, press SHIFT 


these lines have been added 


AN ALTERNATE METHOD FOR BLOCK COPYING USING THE MENU: 


Rather than have to remember all of the appropriate keystrokes you may want to use the menu 
system to guide you through the coping process. 
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Put the cursor on the first line of the block to be copied. Press F10 to display the menu. Use the 
RIGHT ARROW key to move to the BLOCK selection. Press ENTER to bring up the sub-menu. 
Use the DOWN ARROW key to highlight SET LINE MARKER. Press ENTER. If you still see the 
main menu, press the ESC key until the main menu disappears. 


Use the DOWN ARROW to find the end of the block that you want to copy. Press F10 to display 
the main menu. Use the LEFT ARROW key to move to the EDIT selection. Press ENTER to 
display the sub-menu. Using the DOWN ARROW highlight the COPY TO SCRATCHPAD 
selection. Press ENTER. 


Now position the cursor on the line immediately following the place to insert the copied lines. Press 
F10 to display the main menu. Use the RIGHT ARROW key to move to the EDIT selection. Press 
ENTER to display the sub-menu. Using the DOWN ARROW highlight the PASTE SCRATCHPAD 
selection. Press ENTER. The previously copied lines will now be inserted. 


USE THE MOUSE: 


You can use the mouse to highlight the block of text that you want to copy. Simply use the mouse 
to put the cursor on the first line of text to be copied. Press the left mouse button and hold it down 
while dragging the mouse downward. Notice that the cursor will move down on the screen and 
highlight the lines that it encounters as it moves. 


The menu bar can be displayed by moving the cursor to the top line of the screen using the mouse. 
Click the left mouse button and the menu bar will appear. You can use the mouse to put the cursor 
on the desired menu selection and then click the left mouse button. Follow the menu directions 
given in the previous section to continue the copying process but instead use the mouse to 
manipulate the menu instead of the ARROW keys and the ENTER key. 
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OPENING FILES 


To open an exiting file during an edit session use the following directions. Display the menu by 
pressing the F10 key. Choose the FILE selection. From the sub-menu, use the DOWN ARROW 
to highlight the OPEN selection. Press ENTER. This will bring up a box with a sub-menu. Within 
this box take the SAME BUFFER selection. You will then be asked for the name of the file that you 
want to open. Type the full name and path of the file to be opened. Then press ENTER. 


SAVING FILES 


It is possible to save a file during an edit session. Display the menu by pressing the F10 key. 
Choose the FILE selection. From the sub-menu, use the DOWN ARROW to highlight the SAVE 
AS selection. Press ENTER. This will bring up a box with the words ENTER FILENAME: in itt. 
Type the full name and path of the file to be saved. Then press ENTER. 


If the system already knows what file you are working on (either you opened it from the system or 
you have already saved it using SAVE AS) you do not always have to specify the file name before 
you save it. Under the FILE selection is the SAVE AND CONTINUE selection. Choose this 
selection to save the file under the current working file name. 


SETTING TABS 


Because many programming languages require different spacing and column requirements, it is 
advisable to set tabs. Display the menu by pressing the F10 key. Choose the CONFIG selection. 
From the sub-menu, use the DOWN ARROW to highlight the TAB STOPS selection. Press 
ENTER. This will bring up a box for you to type the required tab stop column numbers. 


Standard tabs: 

COBOL: 8 12 16 20 24 NOTE: 8 and 12 are required the others are for 
indenting code for readability. 

ASSEMBLER: 10 16 40 NOTE: 10 and 16 are required and 40 is for 
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comments. 
ENDING AN EDIT SESSION 
—_— are several ways to end an edit session. 
1. Press the ALT and X keys simultaneously. 


2. Display the menu by pressing the F10 key. Choose the FILE selection. From the sub-menu, 
use the DOWN ARROW to highlight the EXIT selection. Press ENTER. 


Using either of these methods to end an edit session will display a line at the top of the screen. The 
purpose of this line is to ask if you want to save the file before exiting or to abandon any changes 
and exit. Answer YES to save the file before exiting or answer NO to exit without saving. 


bP 
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PUTTING IT ALL TOGETHER 


In order to assimilate all of the previous information, let's actually run a program. Make sure that 
you have read the information on the MVS Batch Facility. You may need to refer to this information 
as we go along. First choose the MVS BATCH menu selection and then log on to MVS. Choose 
selection 1 to create a new file. Name this file: MVSTRAIN.JCL. 


Below is an example of a program comprised of Job Control Language statements. Type 1n this file 
exactly as shown. Make sure that all of the lines start in column one. 


//Z92????A JOB ,'your name! 

/*JOBPARM ROOM=BBBB 

// EXEC IGYWCG, CPARM='APOST, FLAG(W,W) , TEST (STMT) ' 
//COB.SYSIN DD DSN=T90SOB1.MVSTRAIN. PGM, DISP=SHR 
//GO.SYSOUT DD SYSOUT=* 


Make sure that this is typed exactly as shown above with the following exceptions: 
1. Z9?2?27?22A -- replace this with: 
A = any letter or digit 


2. YOUR NAME -- _ replace this with your own name. Make sure that it is enclosed in 
single quotes. 


3. BBBB -- replace this with your four digit bin number. 


Save the file and end the edit session. 


The first time that this program, MVSTRAIN.JCL, or any other program is executed, the output 
should not be printed. 
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Choose selection 3 (Submit a job file to MVS for execution). This will run the program that you just 
typed in. Remember, you will be asked to select the file name from a list of files. 


Once the program has run you can view the output. You can determine the status of the job by 
choosing selection 4 (Update the status of your MVS Batch jobs) and then looking at the current job 
category. If the job number has a'u' after it the job is done and is waiting to be fetched. 


Now choose selection 5 (Fetch the output of an MVS Batch job) to fetch the output of your job and 
place a copy of it in your work directory. 


To view the output choose selection 6 (Display the fetched output of an MVS Batch job) You must 
remember the job number in order to look at the correct output. 


When you are viewing the output you cannot make any changes to this file. This a browser and no 
editing can be done. Make a note of any errors and go back to the original file containing the source 
code (the original program) to make any changes or corrections. Corrections cannot be made from 
the browser; they must be made in the original file. 


Notice that we are not printing the output just to check for mistakes. Printed output is reserved for 
final copies of programs or when errors cannot be deciphered and corrected from the screen. 


WHAT TO LOOK FOR: 


The following example shows what you might see while browsing through a file. Each program's 
output starts out with diagnostic messages. The important parts of this screen are located mid- 
screen. The statements '.COB RC=0000! and '.GO RC=0000' indicate the success or 
failure of the steps contained in this job. This particular program was a COBOL program and, 
therefore, the .COB step is the compiler step. The RC=0000 indicates that the RETURN CODE is 
0. This means that the source code, the program typed by the programmer, compiled with no errors 
or warnings. A return code greater than 0 indicates that errors or warnings have occurred. These 
mistakes need to be located and corrected later in the original file. The same principle applies to the 
.GO step. This is the execution step. A return code of 0 indicates that there were no execution 
errors. Keep in mind that an execution error and a logic error are two different types of errors. A 
program can execute without errors and still have the wrong output. Always check the program 
output to see if the program produced the proper results. 
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SJES2 JOB LOG -- SYSTEM E093 -- NODE NIU 


10.33.02 JOB 535 SHASPU01 IIINNNN JOB PARMS - TIME=(0,5) ,LINES=2,CARDS=100,TA 
10.33.03 JOB 535 S$HASP373 IIINNNN STARTED - INIT 16 - CLASS A - SYS E093 
10.33.03 JOB 535 IEF4031I IIINNNN - STARTED - TIME=10.33.03 


10.33.13 JOB 535 AMSOOOI: STEP END IIINNNN~ .COB RC= 0000 CPU= 00:00 
10.33.17 JOB 535 AMSOOOI: STEP END IIINNNN~ .GO RC= 0000 CPU= 00:00 
10.33.17 JOB 535 IEF404I IIINNNN - ENDED - TIME=10.33.17 

10.33.17 JOB 535 AMSOOOI: JOB END IIINNNN programmer name CPU= 00:00 


The source code follows the diagnostics. Following the listing of the source code, at the end or 
bottom of the file, is a list of compiler or execution errors if any. Use the PAGE UP, PAGE DOWN 
and ARROW keys to move backward or forward through the file. A listing of all of the compiler 
errors is located near the end of the output file. Use the END key to move to the end of the file. 


Learning how to identify errors and determining how to correct them comes with practice. The best 
thing to do is make a list of the compiler or assembler errors and the program line numbers on which 
they occur. Use the PAGE UP, PAGE DOWN and ARROW keys to scroll through the source code 
to see what the errors are and where they are located. The compiler should list the line number for 
each error and a corresponding error message. Once it is clear what the problem is and a method of 
correction has been determined, make a note of the correction on the error list. Next exit the browser 
by pressing F10. Remember these files are for viewing, not changing; therefore, there is no need to 
save the file. 


All corrections must be made in the original file. To return to the original file to make corrections, 
take selection 2 (Edit an existing MVS job file). The program that you ran should not need any 
corrections if you typed everything correctly. If you did not then make your corrections and submit 
it again. 


SUBMITTING WITH PRINTING 


There are only two instances when a job should be submitted with the output directed to the printer. 
First, when all errors have been corrected and the final copy is being printed. Second, when most 
of the errors have been corrected using the output files, except for a few errors that cannot be 
identified when using the screen. It then becomes necessary to print a hard copy to track down the 
problem. 
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Choose selection 7 (Submit a job file to MVS for execution and print) to print your job. Remember, 
you will have to know the file name and then you will have to tell which printer you want the output 
to go to. 


The lab attendants take the output off the printers every fifteen minutes. You must fill out a form 
in the lab to retrieve your output. Check with the lab personnel to verify the output retrieval system 
for that particular lab. 


At the end of each session you should clean out any unnecessary jobs from the fetch queue and from 
your disk. To do this you will use selections 8 (Purge an MVS batch job) and 9 (Delete a fetched 
output file from your work directory). 


Before you log off MVS, if you haven't done so already, this might be a good time to change your 
MVS password. Take selection M (Miscellaneous items), then take selection 4 (Change MVS Batch 
Facility options) and then take selection 1 (Change your MVS password). 


To log off of MVS and exit MVSBatch, take selection X (Exit the MVS Batch Facility). 
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LOG OFF PROCEDURES 


LOG OFF THE NETWORK 





1. If you accessed MVSBatch through the CSL Main Menu, upon exiting MVSBatch, you will again 
be at the CSL Main Menu. 


To log off the network, select 
E. Close Your Current Session. 


from the menu. 


2. If you accessed MVSBatch through Windows, upon exiting MVSBatch, you will again be at the 
main Windows window. 


To log off the network, exit Windows 
a. if you had entered Windows from the CSL Main Menu, select 
E. Close Yourrrent Session. 
from the menu. 


b. if you had entered Windows directly after selecting you class applications, you will 
automatically be logged out. 
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